| VMEM_CREATE(3) | PMDK Programmer's Manual | VMEM_CREATE(3) |
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>
| 2019-02-19 | PMDK - vmem API version 1.1 |