Solidify public API with a public header

Author: staticfloat

README.md

@@ -28,12 +28,34 @@ We note that we have an experimental `Clang.jl`-based symbol extractor that extr
 Because we export both the 32-bit (LP64) and 64-bit (ILP64) interfaces, if clients need header files defining the various BLAS/LAPACK functions, they must include headers defining the appropriate ABI.
 We provide headers broken down by interface (`LP64` vs. `ILP64`) as well as target (e.g. `x86_64-linux-gnu`), so to properly compile your code with headers provided by `libblastrampoline` you must add the appropriate `-I${prefix}/include/${interface}/${target}` flags.
 
-When `libblastrampoline` loads a BLAS/LAPACK library, it will inspect it to determine whether it is a 32-bit (LP64) or 64-bit (ILP64) library, and depending on the result, it will forward from its own 32-bit/64-bit names to the names declared in the library its forwarding to.  This allows automatic usage of multiple libraries with different interfaces but the same symbol names.
+When `libblastrampoline` loads a BLAS/LAPACK library, it will inspect it to determine whether it is a 32-bit (LP64) or 64-bit (ILP64) library, and depending on the result, it will forward from its own 32-bit/64-bit names to the names declared in the library its forwarding to.
+This allows automatic usage of multiple libraries with different interfaces but the same symbol names.
 
-`libblastrampoline` is also cognizant of the f2c calling convention incompatibilities introduced by some libraries such as [Apple's Accelerate](https://developer.apple.com/documentation/accelerate).  It will automatically probe the library to determine its calling convention and employ a return-value conversion routine to fix the `float`/`double` return value differences.  This support is only available on the `x86_64` and `i686` architectures, however these are the only systems on which the incompatibilty exists to our knowledge.
+`libblastrampoline` is also cognizant of the f2c calling convention incompatibilities introduced by some libraries such as [Apple's Accelerate](https://developer.apple.com/documentation/accelerate).
+It will automatically probe the library to determine its calling convention and employ a return-value conversion routine to fix the `float`/`double` return value differences.
+This support is only available on the `x86_64` and `i686` architectures, however these are the only systems on which the incompatibilty exists to our knowledge.
+
+## `libblastrampoline`-specific API
+
+`libblastrampoline` exports a simple configuration API including `lbt_forward()`, `lbt_get_config()`, `lbt_{set,get}_num_threads()`, and more.
+See the [public header file](src/libblastrampoline.h) for the most up-to-date documentation on the `libblastrampoline` API.
+
+**Note**: all `lbt_*` functions should be considered thread-unsafe.
+Do not attempt to load two BLAS libraries one two different threads at the same time.
+
+### Limitations
+
+This library has the ability to work with a mixture of LP64 and ILP64 BLAS libraries, but is slightly hampered on certain platforms that do not have the capability to perform `RTLD_DEEPBIND`-style linking.
+As of the time of this writing, this includes FreeBSD and `musl` Linux.
+The impact of this is that you are unable to load an ILP64 BLAS that exports the typical LP64 names (e.g. `dgemm_`) at the same time as an actual LP64 BLAS (with any naming scheme).
+This is because without `RTLD_DEEPBIND`-style linking semantics, when the ILP64 BLAS tries to call one of its own functions, it will call the function exported by `libblastrampoline` itself, which will result in incorrect values and segfaults.
+To address this, `libblastrampoline` will detect if you attempt to do this and refuse to load a library that would cause this kind of confusion.
+You can always tell if your system is limited in this fashion by calling `lbt_get_config()` and checking the `build_flags` member for the `LBT_BUILDFLAGS_DEEPBINDLESS` flag.
 
 ### Version History
 
-v1.1.0 - Added f2c autodetection for Accelerate.
+v1.2.0 - Added threading getter/setter API, added failure configuration API.
+
+v2.0.0 - Added f2c autodetection for Accelerate, changed public API to `lbt_forward()` from `load_blas_funcs()`.
 
 v1.0.0 - Feburary 2021: Initial release with basic autodetection, LP64/ILP64 mixing and trampoline support.

src/Makefile

@@ -38,6 +38,7 @@ $(builddir)/libblastrampoline.$(SHLIB_EXT): $(MAIN_OBJS)
 install: $(builddir)/libblastrampoline.$(SHLIB_EXT)
 	@mkdir -p $(prefix)/include/libblastrampoline
 	-@cp -Ra $(LBT_ROOT)/include/* $(prefix)/include/libblastrampoline
+	@cp -a $(LBT_ROOT)/src/libblastrampoline.h $(prefix)/include/
 	@mkdir -p $(prefix)/$(binlib)
 	@cp -a $(builddir)/libblastrampoline.$(SHLIB_EXT) $(prefix)/$(binlib)
 ifeq ($(OS),WINNT)

src/libblastrampoline.c

@@ -11,20 +11,7 @@
 uint8_t deepbindless_interfaces_loaded      = 0x00;
 
 /*
- * Load the given `libname`, lookup all registered symbols within our `exported_func_names` list,
- * and `dlsym()` the symbol addresses to load the addresses for forwarding into that library.
- *
- * If `clear` is set to a non-zero value, all symbol addresses will be NULL'ed out before they are
- * looked up in `libname`.  If `clear` is set to zero, symbols that do not exist in `libname` will
- * keep their previous value, which allows for loading a base library, then overriding some symbols
- * with a second shim library, integrating separate BLAS and LAPACK libraries, merging an LP64 and
- * ILP64 library into one, or all three use cases at the same time.
- *
- * Note that on certain platforms (currently musl linux and freebsd) you cannot load a non-suffixed
- * ILP64 and an LP64 BLAS at the same time.  Read the note below about lacking RTLD_DEEPBIND
- * support in the system libc for more details.
- *
- * If `verbose` is set to a non-zero value, it will print out debugging information.
+ * Load `libname`, clearing previous mappings if `clear` is set.
  */
 LBT_DLLEXPORT int lbt_forward(const char * libname, int clear, int verbose) {
     if (verbose) {

src/libblastrampoline.h

@@ -0,0 +1,137 @@
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// This shamelessly stolen from https://github.com/JuliaLang/julia/blob/master/src/support/platform.h
+#if defined(__FreeBSD__)
+#define _OS_FREEBSD_
+#elif defined(__linux__)
+#define _OS_LINUX_
+#elif defined(_WIN32) || defined(_WIN64)
+#define _OS_WINDOWS_
+#elif defined(__APPLE__) && defined(__MACH__)
+#define _OS_DARWIN_
+#elif defined(__EMSCRIPTEN__)
+#define _OS_EMSCRIPTEN_
+#endif
+
+// Borrow definition from `support/dtypes.h`
+#ifdef _OS_WINDOWS_
+# ifdef LIBRARY_EXPORTS
+#  define LBT_DLLEXPORT __declspec(dllexport)
+# else
+#  define LBT_DLLEXPORT __declspec(dllimport)
+# endif
+# define LBT_HIDDEN
+#else
+# if defined(LIBRARY_EXPORTS) && defined(_OS_LINUX)
+#  define LBT_DLLEXPORT __attribute__ ((visibility("protected")))
+# else
+#  define LBT_DLLEXPORT __attribute__ ((visibility("default")))
+# endif
+# define LBT_HIDDEN    __attribute__ ((visibility("hidden")))
+#endif
+
+// The metadata stored on each loaded library
+typedef struct {
+    // The library name as passed to `lbt_forward()`.
+    // To get the absolute path to the library, use `dlpath()` or similar on `handle`.
+    char * libname;
+    void * handle;
+    // The suffix used within this library as autodetected by `lbt_forward`.
+    // Common values are `""` or `"64_"`.
+    const char * suffix;
+    // The interface type  as autodetected by `lbt_forward`, see `LBT_INTERFACE_XXX` below
+    int32_t interface;
+    // The `f2c` status  as autodetected by `lbt_forward`, see `LBT_F2C_XXX` below
+    int32_t f2c;
+} lbt_library_info_t;
+
+// Possible values for `interface` in `lbt_library_info_t`
+#define LBT_INTERFACE_LP64              32
+#define LBT_INTERFACE_ILP64             64
+#define LBT_INTERFACE_UNKNOWN          -1
+
+// Possible values for `f2c` in `lbt_library_info_t`
+#define LBT_F2C_PLAIN                   0
+#define LBT_F2C_REQUIRED                1
+#define LBT_F2C_UNKNOWN                -1
+
+// The config type you get back from `lbt_get_config()`
+typedef struct {
+    // The NULL-terminated list of libraries loaded via `lbt_forward()`.
+    // This list is emptied if `clear` is set to `1` in a future `lbt_forward()` call.
+    lbt_library_info_t ** loaded_libs;
+    // Flags that describe this `libblastrampoline`'s build configuration.
+    // See `LBT_BUILDFLAGS_XXX` below.
+    uint32_t build_flags;
+} lbt_config_t;
+
+// Possible values for `build_flags` in `lbt_config_t`
+#define LBT_BUILDFLAGS_DEEPBINDLESS     0x01
+#define LBT_BUILDFLAGS_F2C_CAPABLE      0x02
+
+/*
+ * Load the given `libname`, lookup all registered symbols within our configured list of exported
+ * symbols and `dlsym()` the symbols to load the addresses for forwarding into that library.
+ *
+ * If `clear` is set to a non-zero value, all symbol addresses will be reset to a pre-set value
+ * before they are looked up in `libname`.  If `clear` is set to zero, symbols that do not exist in
+ * `libname` will keep their previous value, which allows for loading a base library, then overriding
+ * some symbols with a second shim library, integrating separate BLAS and LAPACK libraries, merging an
+ * LP64 and ILP64 library into one, or all three use cases at the same time.  See the docstring for
+ * `lbt_set_default_func` for how to control what `clear` sets.
+ *
+ * Note that on certain platforms (currently musl linux and freebsd) you cannot load a non-suffixed
+ * ILP64 and an LP64 BLAS at the same time.  Read the note in the README about `RTLD_DEEPBIND`
+ * support in the system libc for more details.
+ *
+ * If `verbose` is set to a non-zero value, it will print out debugging information.
+ */
+int lbt_forward(const char * libname, int clear, int verbose);
+
+/*
+ * Returns a structure describing the currently-loaded libraries as well as the build configuration
+ * of this `libblastrampoline` instance.  See the definition of `lbt_config_t` in this header file
+ * for more details.
+ */
+const lbt_config_t * lbt_get_config();
+
+/*
+ * Returns the number of threads configured by the underlying BLAS library.  In the event that
+ * multiple libraries are loaded, returns the maximum over all returned values.  The functions
+ * it calls to determine the number of threads are configurable at runtime, see the docstring
+ * for the `lbt_register_thread_interface()` function, although many common functions (such as
+ * those for `OpenBLAS`, `MKL` and `BLIS`) are already registered by default.
+ */
+int32_t lbt_get_num_threads();
+
+/*
+ * Sets the number of threads in the underlying BLAS library.  In the event that multiple
+ * libraries are loaded, sets them all to the same value.  The functions it calls to actually
+ * set the number of threads are configurable at runtime, see the docstring for the
+ * `lbt_register_thread_interface()` function, although many common functions (such as those
+ * for `OpenBLAS`, `MKL` and `BLIS`) are already registered by default.
+ */
+void lbt_set_num_threads(int32_t num_threads);
+
+/*
+ * Register a new `get_num_threads()`/`set_num_threads()` pair.  These functions are assumed to be
+ * callable via the function prototypes `int32_t getter()` and `void setter(int32_t num_threads)`.
+ * Note that due to register zero-extension on `x86_64` it is permissible that the setter actually
+ * expects an `int64_t`, and the getter may return an `int64_t` as long as the value itself is not
+ * larger than the maximum permissable `int64_t`.
+ *
+ * While `libblastrampoline` has built-in knowledge of some BLAS libraries' getter/setter
+ * functions (such as those for `OpenBLAS`, `MKL` and `BLIS`) and will call them from
+ * `lbt_{get,set}_num_threads()`, if the user loads some exotic BLAS that uses a different symbol
+ * name for this functionality, they must register those getter/setter functions here to have them
+ * automatically called whenever `lbt_{get,set}_num_threads()` is called.
+ */
+void lbt_register_thread_interface(const char * getter, const char * setter);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif

src/libblastrampoline_internal.h

@@ -4,8 +4,8 @@
 #include <string.h>
 #include <unistd.h>
 
-// Load in platform-detection macros
-#include "platform.h"
+// Load in our publicly-defined functions/types
+#include "libblastrampoline.h"
 
 #ifdef _OS_LINUX_
 #include <linux/limits.h>
@@ -45,40 +45,17 @@ extern const void ** exported_func64_addrs[];
 
 // The config type you get back from lbt_get_config()
 #define MAX_TRACKED_LIBS        31
-typedef struct {
-    char * libname;
-    void * handle;
-    const char * suffix;
-    int32_t interface;
-    int32_t f2c;
-} lbt_library_info_t;
-
-#define LBT_INTERFACE_LP64              32
-#define LBT_INTERFACE_ILP64             64
-#define LBT_INTERFACE_UNKNOWN           -1
-
-#define LBT_F2C_PLAIN                   0
-#define LBT_F2C_REQUIRED                1
-#define LBT_F2C_UNKNOWN                 -1
-
-typedef struct {
-    lbt_library_info_t ** loaded_libs;
-    uint32_t build_flags;
-} lbt_config_t;
-
-// The various "build_flags" that LBT can report back to the client
-#define LBT_BUILDFLAGS_DEEPBINDLESS     0x01
-#define LBT_BUILDFLAGS_F2C_CAPABLE      0x02
 
 // Functions in `config.c`
 void init_config();
 void clear_loaded_libraries();
-LBT_DLLEXPORT const lbt_config_t * lbt_get_config();
 void record_library_load(const char * libname, void * handle, const char * suffix, int interface, int f2c);
 
 // Functions in `win_utils.c`
+#ifdef _OS_WINDOWS_
 int wchar_to_utf8(const wchar_t * wstr, char *str, size_t maxlen);
 int utf8_to_wchar(const char * str, wchar_t * wstr, size_t maxlen);
+#endif
 
 // Functions in `dl_utils.c`
 void * load_library(const char * path);

src/platform.h

@@ -74,7 +74,7 @@ LBT_DLLEXPORT int32_t lbt_get_num_threads() {
 /*
  * Sets the given number of threads for all loaded libraries.
  */
-LBT_DLLEXPORT int32_t lbt_set_num_threads(int32_t nthreads) {
+LBT_DLLEXPORT void lbt_set_num_threads(int32_t nthreads) {
     const lbt_config_t * config = lbt_get_config();
     for (int lib_idx=0; config->loaded_libs[lib_idx] != NULL; ++lib_idx) {
         lbt_library_info_t * lib = config->loaded_libs[lib_idx];