libvmem(7)

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       It  is recommended that new code uses memkind(3) instead of libvmem, as
46       this library is no longer actively developed and lacks certain features
47       of  memkind such as NUMA awareness.  Nevertheless, it is mature, and is
48       expected to be maintained for foreseable future.
49
50       libvmem uses the mmap(2) system call to create a pool of volatile memo‐
51       ry.   The  library  is most useful when used with Direct Access storage
52       (DAX), which is memory-addressable  persistent  storage  that  supports
53       load/store  access  without  being  paged via the system page cache.  A
54       Persistent Memory-aware file system is typically used to  provide  this
55       type  of  access.  Memory-mapping a file from a Persistent Memory-aware
56       file system provides the raw memory pools, and  this  library  supplies
57       the more familiar malloc-like interfaces on top of those pools.
58
59       Under  normal usage, libvmem will never print messages or intentionally
60       cause the process to exit.  Exceptions to this  are  prints  caused  by
61       calls to vmem_stats_print(3), or by enabling debugging as described un‐
62       der DEBUGGING AND ERROR HANDLING below.  The library uses  pthreads  to
63       be  fully  MT-safe,  but never creates or destroys threads itself.  The
64       library does not make use of any signals, networking, and  never  calls
65       select(2)  or poll(2).  The system memory allocation routines like mal‐
66       loc(3) and free(3) are used by libvmem for managing a small  amount  of
67       run-time state, but applications are allowed to override these calls if
68       necessary (see the description of vmem_set_funcs() below).
69
70       libvmem interfaces are grouped into three categories: those that manage
71       memory  pools,  those  providing the basic memory allocation functions,
72       and those interfaces less commonly used for managing  the  overall  li‐
73       brary behavior.
74

MANAGING LIBRARY BEHAVIOR

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

CAVEATS

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

DEBUGGING AND ERROR HANDLING

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

EXAMPLE

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

BUGS

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

ACKNOWLEDGEMENTS

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