.\" Automatically generated by Pandoc 2.1.3
.\"
.TH "VMEM_CREATE" "3" "2018-07-18" "PMDK - vmem API version 1.1" "PMDK Programmer's Manual"
.hy
.\" Copyright 2014-2018, 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[](), \f[B]vmem_create_in_region\f[](),
\f[B]vmem_delete\f[](), \f[B]vmem_check\f[](),
\f[B]vmem_stats_print\f[]() \- volatile memory pool management
.SH SYNOPSIS
.IP
.nf
\f[C]
#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);
\f[]
.fi
.SH DESCRIPTION
.PP
To use \f[B]libvmem\f[], a \f[I]memory pool\f[] is first created.
This is most commonly done with the \f[B]vmem_create\f[]() function
described below.
The other \f[B]libvmem\f[] 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[]() function creates a memory pool and returns an
opaque memory pool handle of type \f[I]VMEM*\f[].
The handle is then used with \f[B]libvmem\f[] functions such as
\f[B]vmem_malloc\f[]() and \f[B]vmem_free\f[]() to provide the familiar
\f[I]malloc\f[]\-like programming model for the memory pool.
.PP
The pool is created by allocating a temporary file in the directory
\f[I]dir\f[], in a fashion similar to \f[B]tmpfile\f[](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[] bytes are allocated and the resulting space is
memory\-mapped.
The minimum \f[I]size\f[] value allowed by the library is defined in
\f[B]<libvmem.h>\f[] as \f[B]VMEM_MIN_POOL\f[].
The maximum allowed size is not limited by \f[B]libvmem\f[], but by the
file system on which \f[I]dir\f[] resides.
The \f[I]size\f[] passed in is the raw size of the memory pool.
\f[B]libvmem\f[] will use some of that space for its own metadata, so
the usable space will be less.
.PP
\f[B]vmem_create\f[]() can also be called with the \f[B]dir\f[] 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[](1).
.PP
\f[B]vmem_create_in_region\f[]() is an alternate \f[B]libvmem\f[] 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[]() is given the memory region explicitly
via the \f[I]addr\f[] and \f[I]size\f[] arguments.
Any data in the region is lost by calling
\f[B]vmem_create_in_region\f[](), which will immediately store its own
data structures for managing the pool there.
As with \f[B]vmem_create\f[](), the minimum \f[I]size\f[] allowed is
defined as \f[B]VMEM_MIN_POOL\f[].
The \f[I]addr\f[] argument must be page aligned.
Undefined behavior occurs if \f[I]addr\f[] does not point to a
contiguous memory region in the virtual address space of the calling
process, or if the \f[I]size\f[] is larger than the actual size of the
memory region pointed to by \f[I]addr\f[].
.PP
The \f[B]vmem_delete\f[]() function releases the memory pool
\f[I]vmp\f[].
If the memory pool was created using \f[B]vmem_create\f[](), deleting it
allows the space to be reclaimed.
.PP
The \f[B]vmem_check\f[]() function performs an extensive consistency
check of all \f[B]libvmem\f[] internal data structures in memory pool
\f[I]vmp\f[].
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[] in
\f[B]libvmem\f[](7)).
During the consistency check performed by \f[B]vmem_check\f[](), other
operations on the same memory pool are locked out.
The checks are all read\-only; \f[B]vmem_check\f[]() never modifies the
memory pool.
This function is mostly useful for \f[B]libvmem\f[] developers during
testing/debugging.
.PP
The \f[B]vmem_stats_print\f[]() function produces messages containing
statistics about the given memory pool.
Output is sent to \f[I]stderr\f[] unless the user sets the environment
variable \f[B]VMEM_LOG_FILE\f[], or the application supplies a
replacement \f[I]print_func\f[] (see \f[B]MANAGING LIBRARY BEHAVIOR\f[]
in \f[B]libvmem\f[](7)).
The \f[I]opts\f[] 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[](3) for more detail (the description of the
available \f[I]opts\f[] above was taken from that man page).
.SH RETURN VALUE
.PP
On success, \f[B]vmem_create\f[]() returns an opaque memory pool handle
of type \f[I]VMEM*\f[].
On error, it returns NULL and sets \f[I]errno\f[] appropriately.
.PP
On success, \f[B]vmem_create_in_region\f[]() returns an opaque memory
pool handle of type \f[I]VMEM*\f[].
On error, it returns NULL and sets \f[I]errno\f[] appropriately.
.PP
The \f[B]vmem_delete\f[]() function returns no value.
.PP
The \f[B]vmem_check\f[]() 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[]() returns \-1.
.PP
The \f[B]vmem_stats_print\f[]() function returns no value.
.SH SEE ALSO
.PP
\f[B]ndctl\-create\-namespace\f[](1), \f[B]jemalloc\f[](3),
\f[B]tmpfile\f[](3), \f[B]libvmem\f[](7) and \f[B]<http://pmem.io>\f[]