REGISTER_XERBLA - override the error-handler without linker stuff

[mohawk2]

Description

Currently, to override BLAS/LAPACK's handling of errors involves defining a xerbla_ (or sometimes xerbla) symbol in your library/executable. This may not work in 2-level namespace environments like macOS.

Instead, this PR allows you to call REGISTER_XERBLA (Fortran) with a replacement handler. There is also an UNREGISTER_XERBLA. This does not address that the new handler must be a Fortran-compatible routine.

There are CBLAS (cblas_register_xerbla) and LAPACKE (LAPACKE_register_xerbla) handlers on the way, but I'm putting this up for review as I believe it already adds value.

I have marked below that the documentation has been updated, because I added a paragraph in the doc-comments of xerbla.f. If more is needed, please let me know.

Checklist

• The documentation has been updated.
• If the PR solves a specific issue, it is set to be closed on merge.

[codecov]

Codecov Report

❌ Patch coverage is 21.87500% with 200 lines in your changes missing coverage. Please review.
✅ Project coverage is 69.36%. Comparing base (9eaccc1) to head (59116dd).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
BLAS/SRC/xerbla.f	66.66%	3 Missing ⚠️
SRC/xerbla.f	66.66%	3 Missing ⚠️
TESTING/LIN/cqrt14.f	0.00%	3 Missing ⚠️
TESTING/LIN/cqrt15.f	0.00%	3 Missing ⚠️
TESTING/LIN/dqrt14.f	0.00%	3 Missing ⚠️
TESTING/LIN/dqrt15.f	0.00%	3 Missing ⚠️
TESTING/LIN/sqrt14.f	0.00%	3 Missing ⚠️
TESTING/LIN/sqrt15.f	0.00%	3 Missing ⚠️
TESTING/LIN/zqrt14.f	0.00%	3 Missing ⚠️
TESTING/LIN/zqrt15.f	0.00%	3 Missing ⚠️
... and 158 more

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1407   +/-   ##
=======================================
  Coverage   69.36%   69.36%           
=======================================
  Files        6122     6122           
  Lines      486337   486381   +44     
  Branches    23268    23268           
=======================================
+ Hits       337330   337372   +42     
- Misses     148569   148571    +2     
  Partials      438      438           

Components	Coverage Δ
BLAS	97.93% <66.66%> (-0.01%)	⬇️
CBLAS	96.98% <ø> (ø)
LAPACK	82.38% <66.66%> (+<0.01%)	⬆️
LAPACKE	2.17% <ø> (ø)
TMGLIB	55.69% <ø> (ø)
BLAS testing	88.34% <100.00%> (+<0.01%)	⬆️
CBLAS testing	89.63% <ø> (ø)
LAPACK testing	82.24% <12.61%> (+<0.01%)	⬆️
LAPACKE testing	∅ <ø> (∅)

Files with missing lines	Coverage Δ
BLAS/TESTING/cblat2.f	85.46% <100.00%> (+<0.01%)	⬆️
BLAS/TESTING/cblat3.f	90.97% <100.00%> (+<0.01%)	⬆️
BLAS/TESTING/dblat2.f	85.38% <100.00%> (+<0.01%)	⬆️
BLAS/TESTING/dblat3.f	89.45% <100.00%> (+<0.01%)	⬆️
BLAS/TESTING/sblat2.f	85.38% <100.00%> (+<0.01%)	⬆️
BLAS/TESTING/sblat3.f	89.45% <100.00%> (+<0.01%)	⬆️
BLAS/TESTING/zblat2.f	85.46% <100.00%> (+<0.01%)	⬆️
BLAS/TESTING/zblat3.f	90.97% <100.00%> (+<0.01%)	⬆️
TESTING/EIG/cchkdmd.f90	75.08% <100.00%> (+0.08%)	⬆️
TESTING/EIG/cchkee.F	80.00% <100.00%> (+0.02%)	⬆️
... and 194 more

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 9eaccc1...59116dd. Read the comment docs.

[ACSimon33]

Hi @mohawk2,

I like the idea a lot, since it would solve all the problems we currently have with error testing (e.g., it doesn't work with shared Windows libs or two-level namespaces) and make it easier for users to use a custom xerbla on all platforms.

A few things to consider:

• Naming: There are precedents from other BLAS/LAPACK libraries (openblas_set_xerbla, mkl_set_xerbla). Also, it might make sense to split the function into two versions, one for BLAS and one for LAPACK, like this: BLAS_SET_XERBLA and LAPACK_SET_XERBLA (or with REGISTER instead of SET). That would cause fewer name symbol clashes, and the user could decide which error handler to replace.
• Return pointers: openblas_set_xerbla and mkl_set_xerbla return the previous xerbla function pointer. I'm not sure yet how easy that would be to replicate when implementing it in Fortran instead of C...
• Testing optimized libs: Linking the testing framework with optimized BLAS/LAPACK would not work until vendors implement it. Not really an issue, since if they want to use the reference test suite, they should implement the missing functions.
• CBLAS/LAPACKE: It would be nice to have corresponding CBLAS and LAPACKE versions that set their xerbla functions. I don't think anything in the PR makes that difficult, so this can be a follow-up discussion and PR.

[ilayn]

There is also a possibility of defining it as a weak symbol so tests can override the regular one. that can limit the surgery to only xerbla. overall I don't think xerbla is a good way to report errors back but it is what it is for now.

[ACSimon33]

There is also a possibility of defining it as a weak symbol so tests can override the regular one. that can limit the surgery to only xerbla. overall I don't think xerbla is a good way to report errors back but it is what it is for now.

Yes, that's how it's currently done in the CBLAS test suite. Won't work on Windows, though. Also, doing that in Fortran would depend on the compilers supporting it (nagfor doesn't without major hacks, ifx & flang maybe).

[ilayn]

I do use it on windows albeit on a C translation and Clang.

Also, doing that in Fortran would depend on the compilers supporting it (nagfor doesn't without major hacks, ifx & flang maybe).

ah then nevermind. Sorry for the noise

[ACSimon33]

I do use it on windows albeit on a C translation and Clang.

Ah, you're right; Clang and Intel do support it on Windows for static libraries. Did you try it with a shared library? Because last time I checked, that was the blocker.

[mohawk2]

Thank you all for your quick responses! As noted in my edit of the PR description, I'm intending to add CBLAS and LAPACKE equivalents. I'll ponder the names, I hadn't properly checked prior art and will do so now.

I'll ponder the idea of different BLAS and LAPACK handlers - is it really true that the current implementation essentially has two similarly-named symbols that are each are getting overridden by the user-supplied one? If so, that seems horrible. I might need to make differently-named entry points for each that call each other, since the user expectation will be a full override for both.

[ACSimon33]

I'll ponder the idea of different BLAS and LAPACK handlers - is it really true that the current implementation essentially has two similarly-named symbols that are each are getting overridden by the user-supplied one? If so, that seems horrible. I might need to make differently-named entry points for each that call each other, since the user expectation will be a full override for both.

Yes, I think using the same REGISTER_XERBLA symbol name in BLAS and LAPACK could mean it only replaces one of the handlers (if we use separate shared libraries). My sugestion would be to have the separate symbols and then one symbol that does both and lives in LAPACK. Something like this:

    BLAS_SET_XERBLA      ->  libblas.so
    LAPACK_SET_XERBLA    ->  liblapack.so
    SET_XERBLA           ->  liblapack.so (calls the other two)
    
    BLAS_RESET_XERBLA    ->  libblas.so
    LAPACK_RESET_XERBLA  ->  liblapack.so
    RESET_XERBLA         ->  liblapack.so (calls the other two)

Edit:

One issue would be that when we are compiling LAPACK with a vendor BLAS lib and they don't implement BLAS_SET_XERBLA yet, SET_XERBLA would call an undefined symbol. So we would need to check if the supplied vendor BLAS contains the symbol and, if not, disable the call via a preprocessor define.