1VMEM_CREATE(3) PMDK Programmer's Manual VMEM_CREATE(3)
2
6 vmem_create(), vmem_create_in_region(), vmem_delete(), vmem_check(),
7 vmem_stats_print() - volatile memory pool management
8
10 #include <libvmem.h>
11 VMEM *vmem_create(const char *dir, size_t size);
13 VMEM *vmem_create_in_region(void *addr, size_t size);
14 void vmem_delete(VMEM *vmp);
15 int vmem_check(VMEM *vmp);
16 void vmem_stats_print(VMEM *vmp, const char *opts);
17
19 To use libvmem, a memory pool is first created. This is most commonly
20 done with the vmem_create() function described below. The other lib‐
21 vmem functions are for less common cases, where applications have spe‐
22 cial needs for creating pools or examining library state.
23 The vmem_create() function creates a memory pool and returns an opaque
25 memory pool handle of type VMEM*. The handle is then used with libvmem
26 functions such as vmem_malloc() and vmem_free() to provide the familiar
27 malloc-like programming model for the memory pool.
28 The pool is created by allocating a temporary file in the directory
30 dir, in a fashion similar to tmpfile(3), so that the file name does not
31 appear when the directory is listed, and the space is automatically
32 freed when the program terminates. size bytes are allocated and the
33 resulting space is memory-mapped. The minimum size value allowed by
34 the library is defined in <libvmem.h> as VMEM_MIN_POOL. The maximum
35 allowed size is not limited by libvmem, but by the file system on which
36 dir resides. The size passed in is the raw size of the memory pool.
37 libvmem will use some of that space for its own metadata, so the usable
38 space will be less.
39 vmem_create() can also be called with the dir argument pointing to a
41 device DAX. In that case the entire device will serve as a volatile
42 pool. Device DAX is the device-centric analogue of Filesystem DAX. It
43 allows memory ranges to be allocated and mapped without need of an in‐
44 tervening file system. For more information please see ndctl-cre‐
45 ate-namespace(1).
46 vmem_create_in_region() is an alternate libvmem entry point for creat‐
48 ing a memory pool. It is for the rare case where an application needs
49 to create a memory pool from an already memory-mapped region. Instead
50 of allocating space from a file system, vmem_create_in_region() is giv‐
51 en the memory region explicitly via the addr and size arguments. Any
52 data in the region is lost by calling vmem_create_in_region(), which
53 will immediately store its own data structures for managing the pool
54 there. As with vmem_create(), the minimum size allowed is defined as
55 VMEM_MIN_POOL. The addr argument must be page aligned. Undefined be‐
56 havior occurs if addr does not point to a contiguous memory region in
57 the virtual address space of the calling process, or if the size is
58 larger than the actual size of the memory region pointed to by addr.
59 The vmem_delete() function releases the memory pool vmp. If the memory
61 pool was created using vmem_create(), deleting it allows the space to
62 be reclaimed.
63 The vmem_check() function performs an extensive consistency check of
65 all libvmem internal data structures in memory pool vmp. Since an er‐
66 ror return indicates memory pool corruption, applications should not
67 continue to use a pool in this state. Additional details about errors
68 found are logged when the log level is at least 1 (see DEBUGGING AND
69 ERROR HANDLING in libvmem(7)). During the consistency check performed
70 by vmem_check(), other operations on the same memory pool are locked
71 out. The checks are all read-only; vmem_check() never modifies the
72 memory pool. This function is mostly useful for libvmem developers
73 during testing/debugging.
74 The vmem_stats_print() function produces messages containing statistics
76 about the given memory pool. Output is sent to stderr unless the user
77 sets the environment variable VMEM_LOG_FILE, or the application sup‐
78 plies a replacement print_func (see MANAGING LIBRARY BEHAVIOR in lib‐
79 vmem(7)). The opts string can either be NULL or it can contain a list
80 of options that change the statistics printed. General information
81 that never changes during execution can be omitted by specifying “g” as
82 a character within the opts string. The characters “m” and “a” can be
83 specified to omit merged arena and per arena statistics, respectively;
84 “b” and “l” can be specified to omit per size class statistics for bins
85 and large objects, respectively. Unrecognized characters are silently
86 ignored. Note that thread caching may prevent some statistics from be‐
87 ing completely up to date. See jemalloc(3) for more detail (the de‐
88 scription of the available opts above was taken from that man page).
89
91 On success, vmem_create() returns an opaque memory pool handle of type
92 VMEM*. On error, it returns NULL and sets errno appropriately.
93 On success, vmem_create_in_region() returns an opaque memory pool han‐
95 dle of type VMEM*. On error, it returns NULL and sets errno appropri‐
96 ately.
97 The vmem_delete() function returns no value.
99 The vmem_check() function returns 1 if the memory pool is found to be
101 consistent, and 0 if the check was performed but the memory pool is not
102 consistent. If the check could not be performed, vmem_check() returns
103 -1.
104 The vmem_stats_print() function returns no value.
106
108 ndctl-create-namespace(1), jemalloc(3), tmpfile(3), libvmem(7) and
109 <http://pmem.io>
110PMDK - vmem API version 1.1 2018-07-18 VMEM_CREATE(3)