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()  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).

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 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.

SEE ALSO

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