libvmem(7)

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

MANAGING LIBRARY BEHAVIOR

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

CAVEATS

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

DEBUGGING AND ERROR HANDLING

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

EXAMPLE

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

BUGS

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

ACKNOWLEDGEMENTS

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