[arrayfire] 63/248: Documentation for unified backend
Ghislain Vaillant
ghisvail-guest at moszumanska.debian.org
Tue Nov 17 15:53:58 UTC 2015
This is an automated email from the git hooks/post-receive script.
ghisvail-guest pushed a commit to branch dfsg-clean
in repository arrayfire.
commit 4923e581a5ed7b46ea682dbbde09ac067daae218
Author: Shehzan Mohammed <shehzan at arrayfire.com>
Date: Fri Sep 18 11:45:45 2015 -0400
Documentation for unified backend
---
docs/details/backend.dox | 32 ++++++++
docs/layout.xml | 1 +
docs/pages/unified_backend.md | 183 ++++++++++++++++++++++++++++++++++++++++++
include/af/backend.h | 16 ++--
include/arrayfire.h | 7 ++
5 files changed, 231 insertions(+), 8 deletions(-)
diff --git a/docs/details/backend.dox b/docs/details/backend.dox
new file mode 100644
index 0000000..c136cff
--- /dev/null
+++ b/docs/details/backend.dox
@@ -0,0 +1,32 @@
+/**
+\addtogroup arrayfire_func
+@{
+
+\defgroup unified_func_setbackend setBackend
+
+\brief Set the current backend when using Unified backend
+
+This is a noop when using one of CPU, CUDA, or OpenCL backend.
+
+However, when using on of those 3 but trying to set it to a different backend
+will return in an exception.
+
+\ingroup unified_func
+\ingroup arrayfire_func
+
+=======================================================================
+
+\defgroup unified_func_getbackendcount getBackendCount
+
+\brief Get the number of backends whose libraries were successfully loaded.
+
+This will be between 0-3. 0 Being no backends were loaded and 3 being all
+backends loaded successfully.
+
+\ingroup unified_func
+\ingroup arrayfire_func
+
+=======================================================================
+
+@}
+*/
diff --git a/docs/layout.xml b/docs/layout.xml
index d637c7f..0d7a187 100644
--- a/docs/layout.xml
+++ b/docs/layout.xml
@@ -7,6 +7,7 @@
<tab type="user" url="\ref using_on_windows" visible="yes" title="Using on Windows"/>
<tab type="user" url="\ref using_on_osx" visible="yes" title="Using on OSX"/>
<tab type="user" url="\ref gettingstarted" visible="yes" title="Getting Started"/>
+ <tab type="user" url="\ref unifiedbackend" visible="yes" title="Unified Backend"/>
<tab type="user" url="\ref matrixmanipulation" visible="yes" title="Matrix Manipulation"/>
<tab type="user" url="\ref indexing" visible="yes" title="Indexing"/>
<tab type="user" url="\ref timing" visible="yes" title="Timing ArrayFire"/>
diff --git a/docs/pages/unified_backend.md b/docs/pages/unified_backend.md
new file mode 100644
index 0000000..cfbb7b0
--- /dev/null
+++ b/docs/pages/unified_backend.md
@@ -0,0 +1,183 @@
+Unified Backend {#unifiedbackend}
+==========
+
+[TOC]
+
+# Introduction
+
+The Unified backend was introduced in ArrayFire with version 3.2.
+While this is not an independent backend, it allows the user to switch between
+the different ArrayFire backends (CPU, CUDA and OpenCL) at runtime.
+
+# Compiling with Unified
+
+The steps to compile with the unified backend are the same as compiling with
+any of the other backends.
+The only change being that the executable needs to be linked with the __af__
+library (`libaf.so` (Linux), `libaf.dylib` (OSX), `af.lib` (Windows)).
+
+Check the Using with [Linux](\ref using_on_linux), [OSX](\ref using_on_osx),
+[Windows](\ref using_on_windows) for more details.
+
+To use with CMake, use the __ArrayFire_Unified_LIBRARIES__ variable.
+
+# Using the Unified Backend
+
+The Unified backend will try to dynamically load the backend libraries. The
+priority of backends is __CUDA -> OpenCL -> CPU__
+
+The most important aspect to note here is that all the libraries the ArrayFire
+libs depend on need to be in the environment paths (`LD_LIBRARY_PATH` /
+`DYLD_LIBRARY_PATH` / `PATH`). If any of the libs are missing, then the library will
+fail to load and the backend will be marked as unavailable.
+
+> Note: For the CUDA backend, ensure that the CUDA NVVM libs/dlls are in the path.
+> These can be easily missed since CUDA installation does not add the paths by default.
+
+# Switching Backends
+
+The \ref af_backend enum stores the possible backends.
+To select a backend, call the \ref setBackend function as shown below.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+af::setBackend(AF_BACKEND_OPENCL); // Sets CUDA as current backend
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To get the count of the number of backends available (the number of `libaf*`
+backend libraries loaded successfully), call the \ref getBackendCount function.
+
+# Example
+
+This example is shortened form of \ref examples/basic.cpp
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}
+#include <arrayfire.h>
+
+void testBackend()
+{
+ af::info();
+ af_print(af::randu(5, 4));
+}
+
+int main()
+{
+ try {
+ printf("Trying CPU Backend\n");
+ af::setBackend(AF_BACKEND_CPU);
+ testBackend();
+ } catch (af::exception& e) {
+ printf("Caught exception when trying CPU backend\n");
+ fprintf(stderr, "%s\n", e.what());
+ }
+
+ try {
+ printf("Trying CUDA Backend\n");
+ af::setBackend(AF_BACKEND_CUDA);
+ testBackend();
+ } catch (af::exception& e) {
+ printf("Caught exception when trying CUDA backend\n");
+ fprintf(stderr, "%s\n", e.what());
+ }
+
+ try {
+ printf("Trying OpenCL Backend\n");
+ af::setBackend(AF_BACKEND_OPENCL);
+ testBackend();
+ } catch (af::exception& e) {
+ printf("Caught exception when trying OpenCL backend\n");
+ fprintf(stderr, "%s\n", e.what());
+ }
+
+ return 0;
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This output would be:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Trying CPU Backend
+ArrayFire v3.2.0 (CPU, 64-bit Linux, build fc7630f)
+[0] Intel: Intel(R) Core(TM) i7-4770K CPU @ 3.50GHz Max threads(8)
+af::randu(5, 4)
+[5 4 1 1]
+ 0.0000 0.2190 0.3835 0.5297
+ 0.1315 0.0470 0.5194 0.6711
+ 0.7556 0.6789 0.8310 0.0077
+ 0.4587 0.6793 0.0346 0.3834
+ 0.5328 0.9347 0.0535 0.0668
+
+Trying CUDA Backend
+ArrayFire v3.2.0 (CUDA, 64-bit Linux, build fc7630f)
+Platform: CUDA Toolkit 7.5, Driver: 355.11
+[0] Quadro K5000, 4093 MB, CUDA Compute 3.0
+af::randu(5, 4)
+[5 4 1 1]
+ 0.7402 0.4464 0.7762 0.2920
+ 0.9210 0.6673 0.2948 0.3194
+ 0.0390 0.1099 0.7140 0.8109
+ 0.9690 0.4702 0.3585 0.1541
+ 0.9251 0.5132 0.6814 0.4452
+
+Trying OpenCL Backend
+ArrayFire v3.2.0 (OpenCL, 64-bit Linux, build fc7630f)
+[0] NVIDIA : Quadro K5000
+-1- INTEL : Intel(R) Core(TM) i7-4770K CPU @ 3.50GHz
+af::randu(5, 4)
+[5 4 1 1]
+ 0.4107 0.0081 0.6600 0.1046
+ 0.8224 0.3775 0.0764 0.8827
+ 0.9518 0.3027 0.0901 0.1647
+ 0.1794 0.6456 0.5933 0.8060
+ 0.4198 0.5591 0.1098 0.5938
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+# Dos and Don'ts
+
+It is very easy to run into exceptions if you are not careful with the
+switching of backends.
+
+### Don't: Do not arrays between different backends
+
+ArrayFire does not track associations between array objects and the backends
+they were created on. Hence, there will be no compiler errors when an array
+created on one backend is used on another. But this is not allowed and will
+result in exceptions and/or segmenation faults. An example of this is as
+follows.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}
+#include <arrayfire.h>
+
+int main()
+{
+ try {
+ af::setBackend(AF_BACKEND_CUDA);
+ af::array A = af::randu(5, 5);
+
+ af::setBackend(AF_BACKEND_OPENCL);
+ af::array B = af::constant(10, 5, 5);
+ af::array C = af::matmul(A, B); // This will throw an exception
+
+ } catch (af::exception& e) {
+ fprintf(stderr, "%s\n", e.what());
+ }
+
+ return 0;
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Do: Use a naming scheme to track arrays and backends
+
+We recommend that you use a technique to track the arrays on the backends. One
+suggested technique would be to use a suffix of `_cpu`, `_cuda`, `_opencl`
+with the array names. So an array created on the CUDA backend would be named
+`myarray_cuda`.
+
+If you have not used the \ref setBackend function anywhere in your code, then
+you do not have to worry about this as all the arrays will be created on the
+same default backend.
+
+### Don't: Do not use custom kernels (CUDA/OpenCL) with the Unified backend
+
+This is another area that is a no go when using the Unified backend. It not
+recommended that you use custom kernels with unified backend. This is mainly
+becuase the Unified backend is meant to be ultra portable and should use only
+ArrayFire and native CPU code.
diff --git a/include/af/backend.h b/include/af/backend.h
index 6318f61..c828fb6 100644
--- a/include/af/backend.h
+++ b/include/af/backend.h
@@ -15,18 +15,18 @@ extern "C" {
#endif
/**
- Changes the compute backend at run time
-
\param[in] bknd takes one of the values of enum \ref af_backend
\returns \ref af_err error code
+
+ \ingroup unified_func_setbackend
*/
AFAPI af_err af_set_backend(const af_backend bknd);
/**
- Gets the number of available backends
-
\param[out] num_backends Number of available backends
\returns \ref af_err error code
+
+ \ingroup unified_func_getbackendcount
*/
AFAPI af_err af_get_backend_count(unsigned* num_backends);
@@ -39,16 +39,16 @@ namespace af
{
/**
- Changes the compute backend at run time
-
\param[in] bknd takes one of the values of enum \ref af_backend
+
+ \ingroup unified_func_setbackend
*/
AFAPI void setBackend(const Backend bknd);
/**
- Gets the number of available backends
-
\returns Number of available backends
+
+ \ingroup unified_func_getbackendcount
*/
AFAPI unsigned getBackendCount();
diff --git a/include/arrayfire.h b/include/arrayfire.h
index 4cbbebd..ec38d68 100644
--- a/include/arrayfire.h
+++ b/include/arrayfire.h
@@ -200,6 +200,13 @@
Reading and writing images
@}
+ @defgroup unified_func Unified API Functions
+ @{
+
+ Functions to set current backend and utilities
+
+ @}
+
@defgroup external Interface Functions
@{
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/arrayfire.git
More information about the debian-science-commits
mailing list