.\" Automatically generated by Pandoc 2.2.1
.\"
.TH "PMEMOBJ_ALLOC" "3" "2019-02-19" "PMDK - pmemobj API version 2.3" "PMDK 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]pmemobj_alloc\f[](), \f[B]pmemobj_xalloc\f[](),
\f[B]pmemobj_zalloc\f[](), \f[B]pmemobj_realloc\f[](),
\f[B]pmemobj_zrealloc\f[](), \f[B]pmemobj_strdup\f[](),
\f[B]pmemobj_wcsdup\f[](), \f[B]pmemobj_alloc_usable_size\f[](),
\f[B]POBJ_NEW\f[](), \f[B]POBJ_ALLOC\f[](), \f[B]POBJ_ZNEW\f[](),
\f[B]POBJ_ZALLOC\f[](), \f[B]POBJ_REALLOC\f[](),
\f[B]POBJ_ZREALLOC\f[](), \f[B]POBJ_FREE\f[]() \- non\-transactional
atomic allocations
.SH SYNOPSIS
.IP
.nf
\f[C]
#include\ <libpmemobj.h>

typedef\ int\ (*pmemobj_constr)(**PMEMobjpool\ *pop,\ void\ *ptr,\ void\ *arg);
int\ pmemobj_alloc(PMEMobjpool\ *pop,\ PMEMoid\ *oidp,\ size_t\ size,
\ \ \ \ uint64_t\ type_num,\ pmemobj_constr\ constructor,\ void\ *arg);
int\ pmemobj_xalloc(PMEMobjpool\ *pop,\ PMEMoid\ *oidp,\ size_t\ size,
\ \ \ \ uint64_t\ type_num,\ uint64_t\ flags,\ pmemobj_constr\ constructor,
\ \ \ \ void\ *arg);\ (EXPERIMENTAL)
int\ pmemobj_zalloc(PMEMobjpool\ *pop,\ PMEMoid\ *oidp,\ size_t\ size,
\ \ \ \ uint64_t\ type_num);
void\ pmemobj_free(PMEMoid\ *oidp);
int\ pmemobj_realloc(PMEMobjpool\ *pop,\ PMEMoid\ *oidp,\ size_t\ size,
\ \ \ \ uint64_t\ type_num);
int\ pmemobj_zrealloc(PMEMobjpool\ *pop,\ PMEMoid\ *oidp,\ size_t\ size,
\ \ \ \ uint64_t\ type_num);
int\ pmemobj_strdup(PMEMobjpool\ *pop,\ PMEMoid\ *oidp,\ const\ char\ *s,
\ \ \ \ uint64_t\ type_num);
int\ pmemobj_wcsdup(PMEMobjpool\ *pop,\ PMEMoid\ *oidp,\ const\ wchar_t\ *s,
\ \ \ \ uint64_t\ type_num);
size_t\ pmemobj_alloc_usable_size(PMEMoid\ oid);

POBJ_NEW(PMEMobjpool\ *pop,\ TOID\ *oidp,\ TYPE,\ pmemobj_constr\ constructor,
\ \ \ \ void\ *arg)
POBJ_ALLOC(PMEMobjpool\ *pop,\ TOID\ *oidp,\ TYPE,\ size_t\ size,
\ \ \ \ pmemobj_constr\ constructor,\ void\ *arg)
POBJ_ZNEW(PMEMobjpool\ *pop,\ TOID\ *oidp,\ TYPE)
POBJ_ZALLOC(PMEMobjpool\ *pop,\ TOID\ *oidp,\ TYPE,\ size_t\ size)
POBJ_REALLOC(PMEMobjpool\ *pop,\ TOID\ *oidp,\ TYPE,\ size_t\ size)
POBJ_ZREALLOC(PMEMobjpool\ *pop,\ TOID\ *oidp,\ TYPE,\ size_t\ size)
POBJ_FREE(TOID\ *oidp)
\f[]
.fi
.SH DESCRIPTION
.PP
Functions described in this document provide the mechanism to allocate,
resize and free objects from the persistent memory pool in a
thread\-safe and fail\-safe manner.
All the routines are atomic with respect to other threads and any
power\-fail interruptions.
If any of these operations is torn by program failure or system crash,
on recovery they are guaranteed to be entirely completed or discarded,
leaving the persistent memory heap and internal object containers in a
consistent state.
.PP
All these functions can be used outside transactions.
Note that operations performed using the non\-transactional API are
considered durable after completion, even if executed within an open
transaction.
Such non\-transactional changes will not be rolled back if the
transaction is aborted or interrupted.
.PP
The allocations are always aligned to a cache\-line boundary.
.PP
The \f[I]pmemobj_constr\f[] type represents a constructor for atomic
allocation from the persistent memory heap associated with memory pool
\f[I]pop\f[].
\f[I]ptr\f[] is a pointer to the allocated memory area and \f[I]arg\f[]
is a user\-defined argument passed to the constructor.
.PP
The \f[B]pmemobj_alloc\f[]() function allocates a new object from the
persistent memory heap associated with memory pool \f[I]pop\f[].
The \f[I]PMEMoid\f[] of the allocated object is stored in \f[I]oidp\f[].
If \f[I]oidp\f[] is NULL, then the newly allocated object may be
accessed only by iterating objects in the object container associated
with the type number \f[I]type_num\f[], as described in
\f[B]POBJ_FOREACH\f[](3).
If \f[I]oidp\f[] points to a memory location from the \f[B]pmemobj\f[]
heap, \f[I]oidp\f[] is modified atomically.
Before returning, \f[B]pmemobj_alloc\f[]() calls the
\f[I]constructor\f[] function, passing the pool handle \f[I]pop\f[], the
pointer to the newly allocated object in \f[I]ptr\f[], and the
\f[I]arg\f[] argument.
It is guaranteed that the allocated object is either properly
initialized, or if the allocation is interrupted before the constructor
completes, the memory space reserved for the object is reclaimed.
\f[I]size\f[] can be any non\-zero value; however, due to internal
padding and object metadata, the actual size of the allocation will
differ from the requested size by at least 64 bytes.
For this reason, making allocations of a size less than 64 bytes is
extremely inefficient and discouraged.
The allocated object is added to the internal container associated with
\f[I]type_num\f[].
.PP
\f[B]pmemobj_xalloc\f[]() is equivalent to \f[B]pmemobj_alloc\f[](), but
with an additional \f[I]flags\f[] argument that is a bitmask of the
following values:
.IP \[bu] 2
\f[B]POBJ_XALLOC_ZERO\f[] \- zero the object (equivalent of
\f[B]pmemobj_zalloc\f[]())
.IP \[bu] 2
\f[B]POBJ_CLASS_ID(class_id)\f[] \- allocate the object from allocation
class \f[I]class_id\f[].
The class id cannot be 0.
.PP
The \f[B]pmemobj_zalloc\f[]() function allocates a new zeroed object
from the persistent memory heap associated with memory pool
\f[I]pop\f[].
The \f[I]PMEMoid\f[] of the allocated object is stored in \f[I]oidp\f[].
If \f[I]oidp\f[] is NULL, then the newly allocated object may be
accessed only by iterating objects in the object container associated
with the type number \f[I]type_num\f[], as described in
\f[B]POBJ_FOREACH\f[](3).
If \f[I]oidp\f[] points to a memory location from the \f[B]pmemobj\f[]
heap, \f[I]oidp\f[] is modified atomically.
\f[I]size\f[] can be any non\-zero value; however, due to internal
padding and object metadata, the actual size of the allocation will
differ from the requested one by at least 64 bytes.
For this reason, making allocations of a size less than 64 bytes is
extremely inefficient and discouraged.
The allocated object is added to the internal container associated with
\f[I]type_num\f[].
.PP
The \f[B]pmemobj_free\f[]() function frees the memory space represented
by \f[I]oidp\f[], which must have been allocated by a previous call to
\f[B]pmemobj_alloc\f[](), \f[B]pmemobj_xalloc\f[](),
\f[B]pmemobj_zalloc\f[](), \f[B]pmemobj_realloc\f[](), or
\f[B]pmemobj_zrealloc\f[]().
\f[B]pmemobj_free\f[]() provides the same semantics as \f[B]free\f[](3),
but instead of operating on the process heap supplied by the system, it
operates on the persistent memory heap.
If \f[I]oidp\f[] is \f[B]OID_NULL\f[], no operation is performed.
If \f[I]oidp\f[] is NULL or if it points to the root object's
\f[I]OID\f[], the behavior of \f[B]pmemobj_free\f[]() is undefined.
\f[I]oidp\f[] is set to \f[B]OID_NULL\f[] after the memory is freed.
If \f[I]oidp\f[] points to a memory location from the \f[B]pmemobj\f[]
heap, \f[I]oidp\f[] is modified atomically.
.PP
The \f[B]pmemobj_realloc\f[]() function changes the size of the object
represented by \f[I]oidp\f[] to \f[I]size\f[] bytes.
\f[B]pmemobj_realloc\f[]() provides similar semantics to
\f[B]realloc\f[](3), but operates on the persistent memory heap
associated with memory pool \f[I]pop\f[].
The resized object is also added or moved to the internal container
associated with type number \f[I]type_num\f[].
The contents will be unchanged in the range from the start of the region
up to the minimum of the old and new sizes.
If the new size is larger than the old size, the added memory will
\f[I]not\f[] be initialized.
If \f[I]oidp\f[] is \f[I]OID_NULL\f[], then the call is equivalent to
\f[I]pmemobj_alloc(pop, size, type_num)\f[].
If \f[I]size\f[] is equal to zero, and \f[I]oidp\f[] is not
\f[B]OID_NULL\f[], then the call is equivalent to
\f[I]pmemobj_free(oid)\f[].
Unless \f[I]oidp\f[] is \f[B]OID_NULL\f[], it must have been allocated
by an earlier call to \f[B]pmemobj_alloc\f[](),
\f[B]pmemobj_xalloc\f[](), \f[B]pmemobj_zalloc\f[](),
\f[B]pmemobj_realloc\f[](), or \f[B]pmemobj_zrealloc\f[]().
Note that the object handle value may change as a result of
reallocation.
If the object was moved, the memory space represented by \f[I]oid\f[] is
reclaimed.
If \f[I]oidp\f[] points to a memory location from the \f[B]pmemobj\f[]
heap, \f[I]oidp\f[] is modified atomically.
If \f[I]oidp\f[] is NULL or if it points to the root object's
\f[I]OID\f[], the behavior of \f[B]pmemobj_realloc\f[]() is undefined.
.PP
\f[B]pmemobj_zrealloc\f[]() is equivalent to \f[B]pmemobj_realloc\f[](),
except that if the new size is larger than the old size, the added
memory will be zeroed.
.PP
The \f[B]pmemobj_strdup\f[]() function stores a handle to a new object
in \f[I]oidp\f[] which is a duplicate of the string \f[I]s\f[].
\f[B]pmemobj_strdup\f[]() provides the same semantics as
\f[B]strdup\f[](3), but operates on the persistent memory heap
associated with memory pool \f[I]pop\f[].
If \f[I]oidp\f[] is NULL, then the newly allocated object may be
accessed only by iterating objects in the object container associated
with type number \f[I]type_num\f[], as described in
\f[B]POBJ_FOREACH\f[](3).
If \f[I]oidp\f[] points to a memory location from the \f[B]pmemobj\f[]
heap, \f[I]oidp\f[] is modified atomically.
The allocated string object is also added to the internal container
associated with type number \f[I]type_num\f[].
Memory for the new string is obtained with \f[B]pmemobj_alloc\f[](), on
the given memory pool, and can be freed with \f[B]pmemobj_free\f[]() on
the same memory pool.
.PP
\f[B]pmemobj_wcsdup\f[]() is equivalent to \f[B]pmemobj_strdup\f[](),
but operates on a wide character string (wchar_t) rather than a standard
character string.
.PP
The \f[B]pmemobj_alloc_usable_size\f[]() function provides the same
semantics as \f[B]malloc_usable_size\f[](3), but instead of the process
heap supplied by the system, it operates on the persistent memory heap.
.PP
The \f[B]POBJ_NEW\f[]() macro is a wrapper around the
\f[B]pmemobj_alloc\f[]() function.
Instead of taking a pointer to \f[I]PMEMoid\f[], it takes a pointer to
the typed \f[I]OID\f[] of type name \f[I]TYPE\f[], and passes the size
and type number from the typed \f[I]OID\f[] to \f[B]pmemobj_alloc\f[]().
.PP
The \f[B]POBJ_ALLOC\f[]() macro is equivalent to \f[B]POBJ_NEW\f[],
except that instead of using the size of the typed \f[I]OID\f[], passes
\f[I]size\f[] to \f[B]pmemobj_alloc\f[]().
.PP
The \f[B]POBJ_ZNEW\f[]() macro is a wrapper around the
\f[B]pmemobj_zalloc\f[]() function.
Instead of taking a pointer to \f[I]PMEMoid\f[], it takes a pointer to
the typed \f[I]OID\f[] of type name \f[I]TYPE\f[], and passes the size
and type number from the typed \f[I]OID\f[] to
\f[B]pmemobj_zalloc\f[]().
.PP
The \f[B]POBJ_ZALLOC\f[]() macro is equivalent to \f[B]POBJ_ZNEW\f[],
except that instead of using the size of the typed \f[I]OID\f[], passes
\f[I]size\f[] to \f[B]pmemobj_zalloc\f[]().
.PP
The \f[B]POBJ_REALLOC\f[]() macro is a wrapper around the
\f[B]pmemobj_realloc\f[]() function.
Instead of taking a pointer to \f[I]PMEMoid\f[], it takes a pointer to
the typed \f[I]OID\f[] of type name \f[I]TYPE\f[], and passes the type
number from the typed \f[I]OID\f[] to \f[B]pmemobj_realloc\f[]().
.PP
The \f[B]POBJ_ZREALLOC\f[]() macro is a wrapper around the
\f[B]pmemobj_zrealloc\f[]() function.
Instead of taking a pointer to \f[I]PMEMoid\f[], it takes a pointer to
the typed \f[I]OID\f[] of type name \f[I]TYPE\f[], and passes the type
number from the typed \f[I]OID\f[] to \f[B]pmemobj_zrealloc\f[]().
.PP
The \f[B]POBJ_FREE\f[]() macro is a wrapper around the
\f[B]pmemobj_free\f[]() function which takes a pointer to the typed
\f[I]OID\f[] instead of to \f[I]PMEMoid\f[].
.SH RETURN VALUE
.PP
On success, \f[B]pmemobj_alloc\f[]() and \f[B]pmemobj_xalloc\f[] return
0.
If \f[I]oidp\f[] is not NULL, the \f[I]PMEMoid\f[] of the newly
allocated object is stored in \f[I]oidp\f[].
If the allocation fails, \-1 is returned and \f[I]errno\f[] is set
appropriately.
If the constructor returns a non\-zero value, the allocation is
canceled, \-1 is returned, and \f[I]errno\f[] is set to
\f[B]ECANCELED\f[].
If \f[I]size\f[] equals 0, or the \f[I]flags\f[] for
\f[B]pmemobj_xalloc\f[] are invalid, \-1 is returned, \f[I]errno\f[] is
set to \f[B]EINVAL\f[], and \f[I]oidp\f[] is left untouched.
.PP
On success, \f[B]pmemobj_zalloc\f[]() returns 0.
If \f[I]oidp\f[] is not NULL, the \f[I]PMEMoid\f[] of the newly
allocated object is stored in \f[I]oidp\f[].
If the allocation fails, it returns \-1 and sets \f[I]errno\f[]
appropriately.
If \f[I]size\f[] equals 0, it returns \-1, sets \f[I]errno\f[] to
\f[B]EINVAL\f[], and leaves \f[I]oidp\f[] untouched.
.PP
The \f[B]pmemobj_free\f[]() function returns no value.
.PP
On success, \f[B]pmemobj_realloc\f[]() and \f[B]pmemobj_zrealloc\f[]()
return 0 and update \f[I]oidp\f[] if necessary.
On error, they return \-1 and set \f[I]errno\f[] appropriately.
.PP
On success, \f[B]pmemobj_strdup\f[]() and \f[B]pmemobj_wcsdup\f[]()
return 0.
If \f[I]oidp\f[] is not NULL, the \f[I]PMEMoid\f[] of the duplicated
string object is stored in \f[I]oidp\f[].
If \f[I]s\f[] is NULL, they return \-1, set \f[I]errno\f[] to
\f[B]EINVAL\f[], and leave \f[I]oidp\f[] untouched.
On other errors, they return \-1 and set \f[I]errno\f[] appropriately.
.PP
The \f[B]pmemobj_alloc_usable_size\f[]() function returns the number of
usable bytes in the object represented by \f[I]oid\f[].
If \f[I]oid\f[] is \f[B]OID_NULL\f[], it returns 0.
.SH SEE ALSO
.PP
\f[B]free\f[](3), \f[B]POBJ_FOREACH\f[](3), \f[B]realloc\f[](3),
\f[B]strdup\f[](3), \f[B]wcsdup\f[](3), \f[B]libpmemobj\f[](7) and
\f[B]<http://pmem.io>\f[]