arrayfire
diff --git a/‎docs/details/backend.dox‎
Lines changed: 72 additions & 0 deletions b/‎docs/details/backend.dox‎
Lines changed: 72 additions & 0 deletions
diff --git a/‎include/af/backend.h‎
Lines changed: 40 additions & 0 deletions b/‎include/af/backend.h‎
Lines changed: 40 additions & 0 deletions
diff --git a/‎include/af/defines.h‎
Lines changed: 42 additions & 0 deletions b/‎include/af/defines.h‎
Lines changed: 42 additions & 0 deletions
diff --git a/‎src/api/c/device.cpp‎
Lines changed: 9 additions & 0 deletions b/‎src/api/c/device.cpp‎
Lines changed: 9 additions & 0 deletions
diff --git a/‎src/api/unified/device.cpp‎
Lines changed: 13 additions & 0 deletions b/‎src/api/unified/device.cpp‎
Lines changed: 13 additions & 0 deletions
diff --git a/‎src/api/unified/symbol_manager.cpp‎
Lines changed: 82 additions & 6 deletions b/‎src/api/unified/symbol_manager.cpp‎
Lines changed: 82 additions & 6 deletions
diff --git a/‎src/api/unified/symbol_manager.hpp‎
Lines changed: 15 additions & 7 deletions b/‎src/api/unified/symbol_manager.hpp‎
Lines changed: 15 additions & 7 deletions
@@ -16,6 +16,78 @@ will return in an exception.
 
 =======================================================================
 
+\defgroup unified_func_addbackendlibrary af_add_backend_library
+
+\brief Adds a new backend library from an arbitrary path on the file system
+
+This function simply registers a new backend library located anywhere in the
+file system, given the path of that library (can be a `.so`, `.dll`, or
+`.dylib` file, depending on the operating system being used).
+
+Once registered, \ref af_set_backend_library() can be called to activate the
+backend library in a program. The order in which a library is added determines
+the index to be passed in \ref af_set_backend_library() to activate the desired
+library. The number of libraries that can be registered and activated is limited
+to 7.
+
+This function, together with \ref af_set_backend_library() can be used to load
+different versions of the ArrayFire library at runtime.
+
+This is a noop when using any one of the standalone CPU, CUDA, or OpenCL
+backends.
+
+The following is an example of how this can be used:
+\code
+af_add_backend_library("/path/to/custom/1/afcpu.so");
+af_add_backend_library("/path/to/custom/2/afcpu.so");
+
+af_set_backend_library(0); // Activates .../1/afcpu.so
+af_set_backend_library(1); // Activates .../2/afcpu.so
+\endcode
+
+\ingroup unified_func
+\ingroup arrayfire_func
+
+=======================================================================
+
+\defgroup unified_func_setbackendlibrary af_set_backend_library
+
+\brief Activates an ArrayFire library located in an arbitrary path for use
+
+This function is used after the ArrayFire library has been registered through
+\ref af_add_backend_library(). The index to be passed in must be the order of
+when \ref af_add_backend_library() was called for the target library. This is
+can be used to load different versions of the ArrayFire library at runtime.
+
+This is a noop when using any one of the standalone CPU, CUDA, or OpenCL backends.
+
+The following is an example of how this can be used:
+\code
+af_add_backend_library("/path/to/custom/1/afcpu.so");
+af_add_backend_library("/path/to/custom/2/afcpu.so");
+
+af_set_backend_library(0); // Activates .../1/afcpu.so
+af_set_backend_library(1); // Activates .../2/afcpu.so
+\endcode
+
+\ingroup unified_func
+\ingroup arrayfire_func
+
+=======================================================================
+
+\defgroup unified_func_checkunifiedbackend af_check_unified_backend
+
+\brief Returns `true` if the unified backend is used to call ArrayFire functions
+
+This function returns `true` if the unified backend is being used to call the
+ArrayFire functions. If the binary is linked directly to one of the backend
+libraries, this function returns `false`.
+
+\ingroup unified_func
+\ingroup arrayfire_func
+
+=======================================================================
+
 \defgroup unified_func_getbackendcount getBackendCount
 
 \brief Get the number of backends whose libraries were successfully loaded.
 
@@ -24,6 +24,46 @@ extern "C" {
 AFAPI af_err af_set_backend(const af_backend bknd);
 #endif
 
+#if AF_API_VERSION >= 39
+/**
+   Adds a new backend library from an arbitrary path on the file system
+
+   \param[in] lib_path is the path of the custom arrayfire library to
+              be registered
+   \returns   \ref af_err error code
+
+   \ingroup unified_func_addbackendlibrary
+*/
+AFAPI af_err af_add_backend_library(const char *lib_path);
+#endif
+
+#if AF_API_VERSION >= 39
+/**
+   Activates an ArrayFire library located in an arbitrary path for use
+
+   \param[in] lib_idx is the index of a registered custom arrayfire library to
+              be activated for use. Must match the order of when the library
+              was registered
+   \returns   \ref af_err error code
+
+   \ingroup unified_func_setbackendlibrary
+*/
+AFAPI af_err af_set_backend_library(int lib_idx);
+#endif
+
+#if AF_API_VERSION >= 39
+/**
+   Returns true if the unified backend is used to call ArrayFire functions
+
+   \param[out] result reports whether the application is using the unified
+               backend or not
+   \returns    \ref af_err error code
+
+   \ingroup unified_func_checkunifiedbackend
+*/
+AFAPI af_err af_check_unified_backend(bool *result);
+#endif
+
 #if AF_API_VERSION >= 32
 /**
    \param[out] num_backends Number of available backends
 
@@ -193,6 +193,48 @@ typedef enum {
     , AF_ERR_ARR_BKND_MISMATCH    = 503
 #endif
 
+#if AF_API_VERSION >= 39
+    ///
+    /// No active backend
+    ///
+    , AF_ERR_NO_ACTIVE_BKND       = 504
+#endif
+
+#if AF_API_VERSION >= 39
+    ///
+    /// No available devices for this backend
+    ///
+    , AF_ERR_BKND_NO_DEVICE       = 505
+#endif
+
+#if AF_API_VERSION >= 39
+    ///
+    /// Target backend library not available
+    ///
+    , AF_ERR_NO_TGT_BKND_LIB      = 507
+#endif
+
+#if AF_API_VERSION >= 39
+    ///
+    /// Loaded backend library is invalid
+    ///
+    , AF_ERR_BKND_LIB_INVALID     = 508
+#endif
+
+#if AF_API_VERSION >= 39
+    ///
+    /// Backend library list full
+    ///
+    , AF_ERR_BKND_LIB_LIST_FULL   = 509
+#endif
+
+#if AF_API_VERSION >= 39
+    ///
+    /// Backend library index out of bounds
+    ///
+    , AF_ERR_BKND_LIB_IDX_INVALID = 510
+#endif
+
     // 900-999 Errors from upstream libraries and runtimes
 
     ///
 
@@ -59,6 +59,15 @@ af_err af_set_backend(const af_backend bknd) {
     return AF_SUCCESS;
 }
 
+af_err af_add_backend_library(const char* lib_path) { return AF_SUCCESS; }
+
+af_err af_set_backend_library(int lib_idx) { return AF_SUCCESS; }
+
+af_err af_check_unified_backend(bool* result) {
+    *result = false;
+    return AF_SUCCESS;
+}
+
 af_err af_get_backend_count(unsigned* num_backends) {
     *num_backends = 1;
     return AF_SUCCESS;
 
@@ -17,6 +17,19 @@ af_err af_set_backend(const af_backend bknd) {
     return unified::setBackend(bknd);
 }
 
+af_err af_add_backend_library(const char *lib_path) {
+    return unified::AFSymbolManager::getInstance().addBackendLibrary(lib_path);
+}
+
+af_err af_set_backend_library(int lib_idx) {
+    return unified::AFSymbolManager::getInstance().setBackendLibrary(lib_idx);
+}
+
+af_err af_check_unified_backend(bool *result) {
+    *result = true;
+    return AF_SUCCESS;
+}
+
 af_err af_get_backend_count(unsigned *num_backends) {
     *num_backends = unified::AFSymbolManager::getInstance().getBackendCount();
     return AF_SUCCESS;
 
@@ -179,10 +179,19 @@ LibHandle& getActiveHandle() {
     return activeHandle;
 }
 
+LibHandle& getPreviousHandle() {
+    thread_local LibHandle previousHandle =
+        AFSymbolManager::getInstance().getDefaultHandle();
+    return previousHandle;
+}
+
 AFSymbolManager::AFSymbolManager()
-    : defaultHandle(nullptr)
+    : bkndHandles{}
+    , defaultHandle(nullptr)
     , numBackends(0)
+    , newCustomHandleIndex(NUM_BACKENDS)
     , backendsAvailable(0)
+    , defaultBackend(AF_BACKEND_DEFAULT)
     , logger(loggerFactory("unified")) {
     // In order of priority.
     static const af_backend order[] = {AF_BACKEND_CUDA, AF_BACKEND_OPENCL,
@@ -229,20 +238,87 @@ af_err setBackend(af::Backend bknd) {
     auto& instance = AFSymbolManager::getInstance();
     if (bknd == AF_BACKEND_DEFAULT) {
         if (instance.getDefaultHandle()) {
-            getActiveHandle()  = instance.getDefaultHandle();
-            getActiveBackend() = instance.getDefaultBackend();
+            getPreviousHandle() = getActiveHandle();
+            getActiveHandle()   = instance.getDefaultHandle();
+            getActiveBackend()  = instance.getDefaultBackend();
             return AF_SUCCESS;
         } else {
-            UNIFIED_ERROR_LOAD_LIB();
+            UNIFIED_ERROR_LOAD_LIB(AF_ERR_NO_TGT_BKND_LIB);
         }
     }
     int idx = bknd >> 1U;  // Convert 1, 2, 4 -> 0, 1, 2
     if (instance.getHandle(idx)) {
-        getActiveHandle()  = instance.getHandle(idx);
+        getPreviousHandle() = getActiveHandle();
+        getActiveHandle()   = instance.getHandle(idx);
+        getActiveBackend()  = bknd;
+        return AF_SUCCESS;
+    } else {
+        UNIFIED_ERROR_LOAD_LIB(AF_ERR_NO_TGT_BKND_LIB);
+    }
+}
+
+af_err AFSymbolManager::addBackendLibrary(const char* lib_path) {
+    if ((newCustomHandleIndex + 1) > MAX_BKND_HANDLES) {
+        // No more space for an additional handle
+        UNIFIED_ERROR_LOAD_LIB(AF_ERR_BKND_LIB_LIST_FULL);
+    }
+
+    string show_flag    = getEnvVar("AF_SHOW_LOAD_PATH");
+    bool show_load_path = show_flag == "1";
+
+    typedef af_err (*func)(int*);
+    LibHandle handle = nullptr;
+    if ((handle = loadLibrary(lib_path))) {
+        func count_func =
+            (func)getFunctionPointer(handle, "af_get_device_count");
+        if (count_func) {
+            int count = 0;
+            count_func(&count);
+            AF_TRACE("Device Count: {}.", count);
+            if (count == 0) {
+                // No available device for this backend
+                handle = nullptr;
+                UNIFIED_ERROR_LOAD_LIB(AF_ERR_BKND_NO_DEVICE);
+            }
+        } else {
+            // Loaded library is invalid
+            handle = nullptr;
+            UNIFIED_ERROR_LOAD_LIB(AF_ERR_BKND_LIB_INVALID);
+        }
+
+        if (show_load_path) { printf("Using %s\n", lib_path); }
+
+        bkndHandles[newCustomHandleIndex] = handle;
+        newCustomHandleIndex++;
+
+        return AF_SUCCESS;
+    } else {
+        // loadLibrary failed, maybe because path is invalid or another reason
+        UNIFIED_ERROR_LOAD_LIB(AF_ERR_LOAD_LIB);
+    }
+}
+
+af_err AFSymbolManager::setBackendLibrary(int lib_idx) {
+    typedef af_err (*func)(af_backend*);
+    int actual_idx = lib_idx + NUM_BACKENDS;
+
+    if (actual_idx >= MAX_BKND_HANDLES) {
+        // lib_idx more than the capacity of bkndHandles
+        UNIFIED_ERROR_LOAD_LIB(AF_ERR_BKND_LIB_IDX_INVALID);
+    }
+
+    if (bkndHandles[actual_idx]) {
+        getPreviousHandle()   = getActiveHandle();
+        getActiveHandle()     = getHandle(actual_idx);
+        af_backend bknd       = (af_backend)0;
+        func get_backend_func = (func)getFunctionPointer(
+            getActiveHandle(), "af_get_active_backend");
+        if (get_backend_func) { get_backend_func(&bknd); }
         getActiveBackend() = bknd;
         return AF_SUCCESS;
     } else {
-        UNIFIED_ERROR_LOAD_LIB();
+        // lib_idx not pointing to a library yet
+        UNIFIED_ERROR_LOAD_LIB(AF_ERR_NO_TGT_BKND_LIB);
     }
 }
 
 
@@ -23,14 +23,15 @@
 
 namespace unified {
 
-const int NUM_BACKENDS = 3;
+const int NUM_BACKENDS     = 3;
+const int MAX_BKND_HANDLES = 10;
 
-#define UNIFIED_ERROR_LOAD_LIB()                                       \
+#define UNIFIED_ERROR_LOAD_LIB(AF_ERR)                                 \
     AF_RETURN_ERROR(                                                   \
         "Failed to load dynamic library. "                             \
         "See http://www.arrayfire.com/docs/unifiedbackend.htm "        \
         "for instructions to set up environment for Unified backend.", \
-        AF_ERR_LOAD_LIB)
+        AF_ERR)
 
 static inline int backend_index(af::Backend be) {
     switch (be) {
@@ -55,6 +56,9 @@ class AFSymbolManager {
     af::Backend getDefaultBackend() { return defaultBackend; }
     LibHandle getDefaultHandle() { return defaultHandle; }
 
+    af_err addBackendLibrary(const char* lib_path);
+    af_err setBackendLibrary(int lib_idx);
+
     spdlog::logger* getLogger();
     LibHandle getHandle(int idx) { return bkndHandles[idx]; }
 
@@ -69,10 +73,11 @@ class AFSymbolManager {
     void operator=(AFSymbolManager const&);
 
    private:
-    LibHandle bkndHandles[NUM_BACKENDS]{};
+    LibHandle bkndHandles[MAX_BKND_HANDLES]{};
 
     LibHandle defaultHandle;
     unsigned numBackends;
+    unsigned newCustomHandleIndex;
     int backendsAvailable;
     af_backend defaultBackend;
     std::shared_ptr<spdlog::logger> logger;
@@ -84,6 +89,8 @@ af::Backend& getActiveBackend();
 
 LibHandle& getActiveHandle();
 
+LibHandle& getPreviousHandle();
+
 namespace {
 bool checkArray(af_backend activeBackend, const af_array a) {
     // Convert af_array into int to retrieve the backend info.
@@ -144,7 +151,8 @@ bool checkArrays(af_backend activeBackend, T a, Args... arg) {
     if (unified::getActiveHandle()) {                                            \
         thread_local af_func func = (af_func)common::getFunctionPointer(         \
             unified::getActiveHandle(), __func__);                               \
-        if (!func) {                                                             \
+        if (!func &&                                                             \
+            unified::getActiveHandle() != unified::getPreviousHandle()) {        \
             AF_RETURN_ERROR(                                                     \
                 "requested symbol name could not be found in loaded library.",   \
                 AF_ERR_LOAD_LIB);                                                \
@@ -156,8 +164,8 @@ bool checkArrays(af_backend activeBackend, T a, Args... arg) {
         }                                                                        \
         return func(__VA_ARGS__);                                                \
     } else {                                                                     \
-        AF_RETURN_ERROR("ArrayFire couldn't locate any backends.",               \
-                        AF_ERR_LOAD_LIB);                                        \
+        AF_RETURN_ERROR("ArrayFire couldn't load active backend",                \
+                        AF_ERR_NO_ACTIVE_BKND);                                  \
     }
 
 #define CALL_NO_PARAMS(FUNCTION) CALL(FUNCTION)