NAME

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

SYNOPSIS

              #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);

DESCRIPTION

       To  use libvmem, a memory pool is first created.  This is most commonly done with the vmem_create() func‐
       tion 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  fa‐
       miliar 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 tmp‐
       file(3), so that the file name does not appear when the directory is listed, and the space  is  automati‐
       cally  freed  when  the  program  terminates.   size bytes are allocated and the resulting space is memo‐
       ry-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 meta‐
       data, 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 in‐
       formation 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.   In‐
       stead  of allocating space from a file system, vmem_create_in_region() is given the memory region explic‐
       itly 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_cre‐
       ate(), 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 con‐
       tinue 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 dur‐
       ing 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 ei‐
       ther 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, re‐
       spectively; “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).

RETURN VALUE

       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 re‐
       turns 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() re‐
       turns -1.

       The vmem_stats_print() function returns no value.

SEE ALSO

       ndctl-create-namespace(1), jemalloc(3), tmpfile(3), libvmem(7) and <http://pmem.io>

VMEM - vmem API version 1.1                        2020-01-31                                     VMEM_CREATE(3)