1VMEM_CREATE(3)             PMDK Programmer's Manual             VMEM_CREATE(3)
2
3
4

NAME

6       vmem_create(),  vmem_create_in_region(),  vmem_delete(),  vmem_check(),
7       vmem_stats_print() - volatile memory pool management
8

SYNOPSIS

10              #include <libvmem.h>
11
12              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

DESCRIPTION

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
24       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
29       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
40       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
47       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
60       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
64       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
75       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

RETURN VALUE

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
94       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
98       The vmem_delete() function returns no value.
99
100       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
105       The vmem_stats_print() function returns no value.
106

SEE ALSO

108       ndctl-create-namespace(1),   jemalloc(3),  tmpfile(3),  libvmem(7)  and
109       <http://pmem.io>
110
111
112
113PMDK - vmem API version 1.1       2018-07-18                    VMEM_CREATE(3)
Impressum