vmem_create(),
vmem_create_in_region(),
vmem_delete(),
vmem_check(),
vmem_stats_print() - volatile memory pool
management
-
#include <libvmem.h>
VMEM *vmem_create(const char *dir, size_t size);
VMEM *vmem_create_in_region(void *addr, size_t size);
void vmem_delete(VMEM *vmp);
int vmem_check(VMEM *vmp);
void vmem_stats_print(VMEM *vmp, const char *opts);
To use
libvmem, a
memory pool is first created. This is most
commonly done with the
vmem_create() function described below. The
other
libvmem functions are for less common cases, where applications
have special needs for creating pools or examining library state.
The
vmem_create() function creates a memory pool and returns an opaque
memory pool handle of type
VMEM*. The handle is then used with
libvmem functions such as
vmem_malloc() and
vmem_free()
to provide the familiar
malloc-like programming model for the memory
pool.
The pool is created by allocating a temporary file in the directory
dir,
in a fashion similar to
tmpfile(3), so that the file name does not
appear when the directory is listed, and the space is automatically freed when
the program terminates.
size bytes are allocated and the resulting
space is memory-mapped. The minimum
size value allowed by the library
is defined in
<libvmem.h> as
VMEM_MIN_POOL. The maximum
allowed size is not limited by
libvmem, but by the file system on which
dir resides. The
size passed in is the raw size of the memory
pool.
libvmem will use some of that space for its own metadata, so the
usable space will be less.
vmem_create() can also be called with the
dir argument pointing to
a device DAX. In that case the entire device will serve as a volatile pool.
Device DAX is the device-centric analogue of Filesystem DAX. It allows memory
ranges to be allocated and mapped without need of an intervening file system.
For more information please see
ndctl-create-namespace(1).
vmem_create_in_region() is an alternate
libvmem entry point for
creating a memory pool. It is for the rare case where an application needs to
create a memory pool from an already memory-mapped region. Instead of
allocating space from a file system,
vmem_create_in_region() is given
the memory region explicitly via the
addr and
size arguments.
Any data in the region is lost by calling
vmem_create_in_region(),
which will immediately store its own data structures for managing the pool
there. As with
vmem_create(), the minimum
size allowed is
defined as
VMEM_MIN_POOL. The
addr argument must be page
aligned. Undefined behavior occurs if
addr does not point to a
contiguous memory region in the virtual address space of the calling process,
or if the
size is larger than the actual size of the memory region
pointed to by
addr.
The
vmem_delete() function releases the memory pool
vmp. If the
memory pool was created using
vmem_create(), deleting it allows the
space to be reclaimed.
The
vmem_check() function performs an extensive consistency check of all
libvmem internal data structures in memory pool
vmp. Since an
error return indicates memory pool corruption, applications should not
continue to use a pool in this state. Additional details about errors found
are logged when the log level is at least 1 (see
DEBUGGING AND ERROR
HANDLING in
libvmem(7)). During the consistency check performed by
vmem_check(), other operations on the same memory pool are locked out.
The checks are all read-only;
vmem_check() never modifies the memory
pool. This function is mostly useful for
libvmem developers during
testing/debugging.
The
vmem_stats_print() function produces messages containing statistics
about the given memory pool. Output is sent to
stderr unless the user
sets the environment variable
VMEM_LOG_FILE, or the application
supplies a replacement
print_func (see
MANAGING LIBRARY BEHAVIOR
in
libvmem(7)). The
opts string can either be NULL or it can
contain a list of options that change the statistics printed. General
information that never changes during execution can be omitted by specifying
“g” as a character within the opts string. The characters
“m” and “a” can be specified to omit merged arena
and per arena statistics, respectively; “b” and
“l” can be specified to omit per size class statistics for bins
and large objects, respectively. Unrecognized characters are silently ignored.
Note that thread caching may prevent some statistics from being completely up
to date. See
jemalloc(3) for more detail (the description of the
available
opts above was taken from that man page).
On success,
vmem_create() returns an opaque memory pool handle of type
VMEM*. On error, it returns NULL and sets
errno appropriately.
On success,
vmem_create_in_region() returns an opaque memory pool handle
of type
VMEM*. On error, it returns NULL and sets
errno
appropriately.
The
vmem_delete() function returns no value.
The
vmem_check() function returns 1 if the memory pool is found to be
consistent, and 0 if the check was performed but the memory pool is not
consistent. If the check could not be performed,
vmem_check() returns
-1.
The
vmem_stats_print() function returns no value.
ndctl-create-namespace(1),
jemalloc(3),
tmpfile(3),
libvmem(7) and
<http://pmem.io>