vmem_check_version(3)

1LIBVMEM(7)                 PMDK Programmer's Manual                 LIBVMEM(7)
2
3
4

NAME

6       libvmem -- volatile memory allocation library
7

SYNOPSIS

9              #include <libvmem.h>
10              cc ... -lvmem
11
12   Managing overall library behavior:
13              const char *vmem_check_version(
14                  unsigned major_required,
15                  unsigned minor_required);
16
17              void vmem_set_funcs(
18                  void *(*malloc_func)(size_t size),
19                  void (*free_func)(void *ptr),
20                  void *(*realloc_func)(void *ptr, size_t size),
21                  char *(*strdup_func)(const char *s),
22                  void (*print_func)(const char *s));
23
24   Error handling:
25              const char *vmem_errormsg(void);
26
27   Other library functions:
28       A  description of other libvmem functions can be found on the following
29       manual pages:
30
31       · memory pool management: vmem_create(3)
32
33       · memory allocation related functions: vmem_malloc(3)
34

DESCRIPTION

36       libvmem provides common malloc-like interfaces to memory pools built on
37       memory-mapped  files.   These  interfaces  are for traditional volatile
38       memory allocation but, unlike the functions described in malloc(3), the
39       memory  managed  by libvmem may have different attributes, depending on
40       the file system containing the  memory-mapped  files.   In  particular,
41       libvmem  is part of the Persistent Memory Development Kit because it is
42       sometimes useful to use non-volatile memory as a volatile memory  pool,
43       leveraging its capacity, cost, or performance characteristics.
44
45       libvmem uses the mmap(2) system call to create a pool of volatile memo‐
46       ry.  The library is most useful when used with  Direct  Access  storage
47       (DAX),  which  is  memory-addressable  persistent storage that supports
48       load/store access without being paged via the  system  page  cache.   A
49       Persistent  Memory-aware  file system is typically used to provide this
50       type of access.  Memory-mapping a file from a  Persistent  Memory-aware
51       file  system  provides  the raw memory pools, and this library supplies
52       the more familiar malloc-like interfaces on top of those pools.
53
54       Under normal usage, libvmem will never print messages or  intentionally
55       cause  the  process  to  exit.  Exceptions to this are prints caused by
56       calls to vmem_stats_print(3), or by enabling debugging as described un‐
57       der  DEBUGGING  AND ERROR HANDLING below.  The library uses pthreads to
58       be fully MT-safe, but never creates or destroys  threads  itself.   The
59       library  does  not make use of any signals, networking, and never calls
60       select(2) or poll(2).  The system memory allocation routines like  mal‐
61       loc(3)  and  free(3) are used by libvmem for managing a small amount of
62       run-time state, but applications are allowed to override these calls if
63       necessary (see the description of vmem_set_funcs() below).
64
65       libvmem interfaces are grouped into three categories: those that manage
66       memory pools, those providing the basic  memory  allocation  functions,
67       and  those  interfaces  less commonly used for managing the overall li‐
68       brary behavior.
69

MANAGING LIBRARY BEHAVIOR

71       The vmem_check_version() function is used to see if the installed  lib‐
72       vmem  supports  the  version of the library API required by an applica‐
73       tion.  The easiest way to do this is for the application to supply  the
74       compile-time  version  information, supplied by defines in <libvmem.h>,
75       like this:
76
77              reason = vmem_check_version(VMEM_MAJOR_VERSION,
78                                          VMEM_MINOR_VERSION);
79              if (reason != NULL) {
80                  /* version check failed, reason string tells you why */
81              }
82
83       Any mismatch in the major version number is considered a failure, but a
84       library  with  a  newer minor version number will pass this check since
85       increasing minor versions imply backwards compatibility.
86
87       An application can also check specifically for the existence of an  in‐
88       terface  by  checking  for  the version where that interface was intro‐
89       duced.  These versions are documented in this man page as follows:  un‐
90       less  otherwise  specified, all interfaces described here are available
91       in version 1.0 of the library.  Interfaces added after version 1.0 will
92       contain the text introduced in version x.y in the section of this manu‐
93       al describing the feature.
94
95       When the version  check  is  successful,  vmem_check_version()  returns
96       NULL.  Otherwise, vmem_check_version() returns a static string describ‐
97       ing the reason for failing the version check.  The returned string must
98       not be modified or freed.
99
100       The  vmem_set_funcs()  function  allows an application to override some
101       interfaces used internally by libvmem.  Passing NULL  for  any  of  the
102       handlers  will cause the libvmem default function to be used.  The only
103       functions in the malloc family used by the library are  represented  by
104       the  first  four arguments to vmem_set_funcs().  While the library does
105       not make heavy use of the system malloc functions, it does allocate ap‐
106       proximately  4-8 kilobytes for each memory pool in use.  The print_func
107       function is called by libvmem when the vmem_stats_print()  entry  point
108       is  used, or when additional tracing is enabled in the debug version of
109       the library as described in DEBUGGING AND ERROR HANDLING,  below.   The
110       default  print_func used by the library prints to the file specified by
111       the VMEM_LOG_FILE environment variable, or to stderr if  that  variable
112       is not set.
113

CAVEATS

115       libvmem  relies  on  the  library destructor being called from the main
116       thread.  For this reason, all functions that might trigger  destruction
117       (e.g.  dlclose(3)) should be called in the main thread.  Otherwise some
118       of the resources associated with that thread might not  be  cleaned  up
119       properly.
120

DEBUGGING AND ERROR HANDLING

122       If  an error is detected during the call to a libvmem function, the ap‐
123       plication may retrieve an error message describing the reason  for  the
124       failure  from  vmem_errormsg().   This  function returns a pointer to a
125       static buffer containing the last error message logged for the  current
126       thread.   If errno was set, the error message may include a description
127       of the corresponding error code as returned by strerror(3).  The  error
128       message buffer is thread-local; errors encountered in one thread do not
129       affect its value in other threads.  The buffer is never cleared by  any
130       library function; its content is significant only when the return value
131       of the immediately preceding call to a libvmem  function  indicated  an
132       error,  or  if  errno was set.  The application must not modify or free
133       the error message string, but it may be modified by subsequent calls to
134       other library functions.
135
136       Two  versions  of libvmem are typically available on a development sys‐
137       tem.  The normal version is optimized for  performance.   That  version
138       skips  checks that impact performance and never logs any trace informa‐
139       tion or performs any run-time assertions.  A second  version,  accessed
140       when using libraries from /usr/lib/pmdk_debug, contains run-time asser‐
141       tions and trace points.  The typical way to access the debug version is
142       to  set the LD_LIBRARY_PATH environment variable to /usr/lib/pmdk_debug
143       or /usr/lib64/pmdk_debug, as appropriate.   Debugging  output  is  con‐
144       trolled  using  the  following  environment variables.  These variables
145       have no effect on the non-debug version of the library.
146
147       · VMEM_LOG_LEVEL
148
149       The value of VMEM_LOG_LEVEL enables trace points in the  debug  version
150       of the library, as follows:
151
152       · 0   -   Tracing   is  disabled.   This  is  the  default  level  when
153         VMEM_LOG_LEVEL is not set.  Only statistics are logged, and then only
154         in response to a call to vmem_stats_print().
155
156       · 1 - Additional details on any errors detected are logged, in addition
157         to returning the errno-based errors as usual.
158
159       · 2 - A trace of basic operations is logged.
160
161       · 3 - Enables a very verbose amount of function call tracing in the li‐
162         brary.
163
164       · 4  -  Enables voluminous tracing information about all memory alloca‐
165         tions and deallocations.
166
167       Unless VMEM_LOG_FILE is set, debugging output is written to stderr.
168
169       · VMEM_LOG_FILE
170
171       Specifies the name of a file where all logging  information  should  be
172       written.  If the last character in the name is "-", the PID of the cur‐
173       rent process will be appended to the file name when  the  log  file  is
174       created.  If VMEM_LOG_FILE is not set, output is written to stderr.
175

EXAMPLE

177       The  following  example creates a memory pool, allocates some memory to
178       contain the string "hello, world", and then frees that memory.
179
180              #include <stdio.h>
181              #include <stdlib.h>
182              #include <string.h>
183              #include <libvmem.h>
184
185              int
186              main(int argc, char *argv[])
187              {
188                  VMEM *vmp;
189                  char *ptr;
190
191                  /* create minimum size pool of memory */
192                  if ((vmp = vmem_create("/pmem-fs",
193                          VMEM_MIN_POOL)) == NULL) {
194                      perror("vmem_create");
195                      exit(1);
196                  }
197
198                  if ((ptr = vmem_malloc(vmp, 100)) == NULL) {
199                      perror("vmem_malloc");
200                      exit(1);
201                  }
202
203                  strcpy(ptr, "hello, world");
204
205                  /* give the memory back */
206                  vmem_free(vmp, ptr);
207
208                  /* ... */
209
210                  vmem_delete(vmp);
211              }
212
213       See <http://pmem.io/pmdk/libvmem> for more examples using  the  libvmem
214       API.
215

BUGS

217       Unlike the normal malloc(3), which asks the system for additional memo‐
218       ry when it runs out, libvmem allocates the size it is told to and never
219       attempts to grow or shrink that memory pool.
220

ACKNOWLEDGEMENTS

222       libvmem  depends  on  jemalloc, written by Jason Evans, to do the heavy
223       lifting of managing dynamic memory allocation.  See: <http://www.canon‐
224       ware.com/jemalloc>
225
226       libvmem  builds  on the persistent memory programming model recommended
227       by    the    SNIA    NVM    Programming    Technical    Work     Group:
228       <http://snia.org/nvmp>
229