.\" Automatically generated by Pandoc 2.5 .\" .TH "VMEM_CREATE" "3" "2019-11-08" "VMEM - vmem API version 1.1" "VMEM Programmer's Manual" .hy .\" Copyright 2014-2019, Intel Corporation .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in .\" the documentation and/or other materials provided with the .\" distribution. .\" .\" * Neither the name of the copyright holder nor the names of its .\" contributors may be used to endorse or promote products derived .\" from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT .\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE .\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .SH NAME .PP \f[B]vmem_create\f[R](), \f[B]vmem_create_in_region\f[R](), \f[B]vmem_delete\f[R](), \f[B]vmem_check\f[R](), \f[B]vmem_stats_print\f[R]() \- volatile memory pool management .SH SYNOPSIS .IP .nf \f[C] #include 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); \f[R] .fi .SH DESCRIPTION .PP To use \f[B]libvmem\f[R], a \f[I]memory pool\f[R] is first created. This is most commonly done with the \f[B]vmem_create\f[R]() function described below. The other \f[B]libvmem\f[R] functions are for less common cases, where applications have special needs for creating pools or examining library state. .PP The \f[B]vmem_create\f[R]() function creates a memory pool and returns an opaque memory pool handle of type \f[I]VMEM*\f[R]. The handle is then used with \f[B]libvmem\f[R] functions such as \f[B]vmem_malloc\f[R]() and \f[B]vmem_free\f[R]() to provide the familiar \f[I]malloc\f[R]\-like programming model for the memory pool. .PP The pool is created by allocating a temporary file in the directory \f[I]dir\f[R], in a fashion similar to \f[B]tmpfile\f[R](3), so that the file name does not appear when the directory is listed, and the space is automatically freed when the program terminates. \f[I]size\f[R] bytes are allocated and the resulting space is memory\-mapped. The minimum \f[I]size\f[R] value allowed by the library is defined in \f[B]\f[R] as \f[B]VMEM_MIN_POOL\f[R]. The maximum allowed size is not limited by \f[B]libvmem\f[R], but by the file system on which \f[I]dir\f[R] resides. The \f[I]size\f[R] passed in is the raw size of the memory pool. \f[B]libvmem\f[R] will use some of that space for its own metadata, so the usable space will be less. .PP \f[B]vmem_create\f[R]() can also be called with the \f[B]dir\f[R] 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 \f[B]ndctl\-create\-namespace\f[R](1). .PP \f[B]vmem_create_in_region\f[R]() is an alternate \f[B]libvmem\f[R] 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, \f[B]vmem_create_in_region\f[R]() is given the memory region explicitly via the \f[I]addr\f[R] and \f[I]size\f[R] arguments. Any data in the region is lost by calling \f[B]vmem_create_in_region\f[R](), which will immediately store its own data structures for managing the pool there. As with \f[B]vmem_create\f[R](), the minimum \f[I]size\f[R] allowed is defined as \f[B]VMEM_MIN_POOL\f[R]. The \f[I]addr\f[R] argument must be page aligned. Undefined behavior occurs if \f[I]addr\f[R] does not point to a contiguous memory region in the virtual address space of the calling process, or if the \f[I]size\f[R] is larger than the actual size of the memory region pointed to by \f[I]addr\f[R]. .PP The \f[B]vmem_delete\f[R]() function releases the memory pool \f[I]vmp\f[R]. If the memory pool was created using \f[B]vmem_create\f[R](), deleting it allows the space to be reclaimed. .PP The \f[B]vmem_check\f[R]() function performs an extensive consistency check of all \f[B]libvmem\f[R] internal data structures in memory pool \f[I]vmp\f[R]. 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 \f[B]DEBUGGING AND ERROR HANDLING\f[R] in \f[B]libvmem\f[R](7)). During the consistency check performed by \f[B]vmem_check\f[R](), other operations on the same memory pool are locked out. The checks are all read\-only; \f[B]vmem_check\f[R]() never modifies the memory pool. This function is mostly useful for \f[B]libvmem\f[R] developers during testing/debugging. .PP The \f[B]vmem_stats_print\f[R]() function produces messages containing statistics about the given memory pool. Output is sent to \f[I]stderr\f[R] unless the user sets the environment variable \f[B]VMEM_LOG_FILE\f[R], or the application supplies a replacement \f[I]print_func\f[R] (see \f[B]MANAGING LIBRARY BEHAVIOR\f[R] in \f[B]libvmem\f[R](7)). The \f[I]opts\f[R] 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 \[lq]g\[rq] as a character within the opts string. The characters \[lq]m\[rq] and \[lq]a\[rq] can be specified to omit merged arena and per arena statistics, respectively; \[lq]b\[rq] and \[lq]l\[rq] 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 \f[B]jemalloc\f[R](3) for more detail (the description of the available \f[I]opts\f[R] above was taken from that man page). .SH RETURN VALUE .PP On success, \f[B]vmem_create\f[R]() returns an opaque memory pool handle of type \f[I]VMEM*\f[R]. On error, it returns NULL and sets \f[I]errno\f[R] appropriately. .PP On success, \f[B]vmem_create_in_region\f[R]() returns an opaque memory pool handle of type \f[I]VMEM*\f[R]. On error, it returns NULL and sets \f[I]errno\f[R] appropriately. .PP The \f[B]vmem_delete\f[R]() function returns no value. .PP The \f[B]vmem_check\f[R]() 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, \f[B]vmem_check\f[R]() returns \-1. .PP The \f[B]vmem_stats_print\f[R]() function returns no value. .SH SEE ALSO .PP \f[B]ndctl\-create\-namespace\f[R](1), \f[B]jemalloc\f[R](3), \f[B]tmpfile\f[R](3), \f[B]libvmem\f[R](7) and \f[B]\f[R]