[arrayfire] 38/84: MEMINFO -> AF_MEM_INFO. Add documentation for the macro

[Ghislain Vaillant]

This is an automated email from the git hooks/post-receive script.

ghisvail-guest pushed a commit to branch master
in repository arrayfire.

commit 0b11c6efc7b012197a2288db6463e7a355b5d76b
Author: Shehzan Mohammed <shehzan at arrayfire.com>
Date:   Wed Dec 16 17:25:29 2015 -0500

    MEMINFO -> AF_MEM_INFO. Add documentation for the macro
---
 include/af/macros.h | 56 +++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 52 insertions(+), 4 deletions(-)

diff --git a/include/af/macros.h b/include/af/macros.h
index 65077dc..3c52321 100644
--- a/include/af/macros.h
+++ b/include/af/macros.h
@@ -22,15 +22,63 @@
         } while (0);
 #endif
 
-#define MEMINFO(msg) do {                                                               \
+/**
+ * AF_MEM_INFO macro can be used to print the current stats of ArrayFire's memory
+ * manager.
+ *
+ * AF_MEM_INFO print 4 values:
+ *
+ * ---------------------------------------------------
+ *  Name                    | Description
+ * -------------------------|-------------------------
+ *  Allocated Bytes         | Total number of bytes allocated by the memory manager
+ *  Allocated Buffers       | Total number of buffers allocated
+ *  Locked (In Use) Bytes   | Number of bytes that are in use by active arrays
+ *  Locked (In Use) Buffers | Number of buffers that are in use by active arrays
+ * ---------------------------------------------------
+ *
+ *  The `Allocated Bytes` is always a multiple of the memory step size. The
+ *  default step size is 1024 bytes. This means when a buffer is to be
+ *  allocated, the size is always rounded up to a multiple of the step size.
+ *  You can use af::getMemStepSize() to check the current step size and
+ *  af::setMemStepSize() to set a custom resolution size.
+ *
+ *  The `Allocated Buffers` is the number of buffers that use up the allocated
+ *  bytes. This includes buffers currently in scope, as well as buffers marked
+ *  as free, ie, from arrays gone out of scope. The free buffers are available
+ *  for use by new arrays that might be created.
+ *
+ *  The `Locked Bytes` is the number of bytes in use that cannot be
+ *  reallocated at the moment. The difference of Allocated Bytes and Locked
+ *  Bytes is the total bytes available for reallocation.
+ *
+ *  The `Locked Buffers` is the number of buffer in use that cannot be
+ *  reallocated at the moment. The difference of Allocated Buffers and Locked
+ *  Buffers is the number of buffers available for reallocation.
+ *
+ * The AF_MEM_INFO macro can accept a string an argument that is printed to screen
+ *
+ * \param[in] msg (Optional) A message that is printed to screen
+ *
+ * \code
+ *     AF_MEM_INFO("At start");
+ * \endcode
+ *
+ * Output:
+ *
+ *     AF Memory at /workspace/myfile.cpp:41: At Start
+ *     Allocated [ Bytes | Buffers ] = [ 4096 | 4 ]
+ *     In Use    [ Bytes | Buffers ] = [ 2048 | 2 ]
+ */
+#define AF_MEM_INFO(msg) do {                                                           \
     size_t abytes = 0, abuffs = 0, lbytes = 0, lbuffs = 0;                              \
     af_err err = af_device_mem_info(&abytes, &abuffs, &lbytes, &lbuffs);                \
     if(err == AF_SUCCESS) {                                                             \
-        printf("MemInfo at %s:%d: " msg "\n", __FILE__, __LINE__);                      \
+        printf("AF Memory at %s:%d: " msg "\n", __FILE__, __LINE__);                    \
         printf("Allocated [ Bytes | Buffers ] = [ %ld | %ld ]\n", abytes, abuffs);      \
         printf("In Use    [ Bytes | Buffers ] = [ %ld | %ld ]\n", lbytes, lbuffs);      \
     } else {                                                                            \
-        fprintf(stderr, "MemInfo at %s:%d: " msg "\nAF Error %d\n",                     \
+        fprintf(stderr, "AF Memory at %s:%d: " msg "\nAF Error %d\n",                   \
                 __FILE__, __LINE__, err);                                               \
     }                                                                                   \
-} while(0);
+} while(0)

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/arrayfire.git