.\" Automatically generated by Pandoc 2.1.3
.\"
.TH "PMEMOBJ_TX_ALLOC" "3" "2018-07-18" "PMDK - pmemobj API version 2.3" "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]pmemobj_tx_alloc\f[](), \f[B]pmemobj_tx_zalloc\f[](),
\f[B]pmemobj_tx_xalloc\f[](), \f[B]pmemobj_tx_realloc\f[](),
\f[B]pmemobj_tx_zrealloc\f[](), \f[B]pmemobj_tx_strdup\f[](),
\f[B]pmemobj_tx_wcsdup\f[](), \f[B]pmemobj_tx_free\f[](),
.PP
\f[B]TX_NEW\f[](), \f[B]TX_ALLOC\f[](), \f[B]TX_ZNEW\f[](),
\f[B]TX_ZALLOC\f[](), \f[B]TX_XALLOC\f[](), \f[B]TX_REALLOC\f[](),
\f[B]TX_ZREALLOC\f[](), \f[B]TX_STRDUP\f[](), \f[B]TX_WCSDUP\f[](),
\f[B]TX_FREE\f[]() \- transactional object manipulation
.SH SYNOPSIS
.IP
.nf
\f[C]
#include\ <libpmemobj.h>
PMEMoid\ pmemobj_tx_alloc(size_t\ size,\ uint64_t\ type_num);
PMEMoid\ pmemobj_tx_zalloc(size_t\ size,\ uint64_t\ type_num);
PMEMoid\ pmemobj_tx_xalloc(size_t\ size,\ uint64_t\ type_num,\ uint64_t\ flags);
PMEMoid\ pmemobj_tx_realloc(PMEMoid\ oid,\ size_t\ size,\ uint64_t\ type_num);
PMEMoid\ pmemobj_tx_zrealloc(PMEMoid\ oid,\ size_t\ size,\ uint64_t\ type_num);
PMEMoid\ pmemobj_tx_strdup(const\ char\ *s,\ uint64_t\ type_num);
PMEMoid\ pmemobj_tx_wcsdup(const\ wchar_t\ *s,\ uint64_t\ type_num);
int\ pmemobj_tx_free(PMEMoid\ oid);
TX_NEW(TYPE)
TX_ALLOC(TYPE,\ size_t\ size)
TX_ZNEW(TYPE)
TX_ZALLOC(TYPE,\ size_t\ size)
TX_XALLOC(TYPE,\ size_t\ size,\ uint64_t\ flags)
TX_REALLOC(TOID\ o,\ size_t\ size)
TX_ZREALLOC(TOID\ o,\ size_t\ size)
TX_STRDUP(const\ char\ *s,\ uint64_t\ type_num)
TX_WCSDUP(const\ wchar_t\ *s,\ uint64_t\ type_num)
TX_FREE(TOID\ o)
\f[]
.fi
.SH DESCRIPTION
.PP
The \f[B]pmemobj_tx_alloc\f[]() function transactionally allocates a new
object of given \f[I]size\f[] and \f[I]type_num\f[].
In contrast to the non\-transactional allocations, the objects are added
to the internal object containers of given \f[I]type_num\f[] only after
the transaction is committed, making the objects visible to the
\f[B]POBJ_FOREACH_*\f[]() macros.
This function must be called during \f[B]TX_STAGE_WORK\f[].
.PP
The \f[B]pmemobj_tx_zalloc\f[]() function transactionally allocates a
new zeroed object of given \f[I]size\f[] and \f[I]type_num\f[].
This function must be called during \f[B]TX_STAGE_WORK\f[].
.PP
The \f[B]pmemobj_tx_xalloc\f[]() function transactionally allocates a
new object of given \f[I]size\f[] and \f[I]type_num\f[].
The \f[I]flags\f[] argument is a bitmask of the following values:
.IP \[bu] 2
\f[B]POBJ_XALLOC_ZERO\f[] \- zero the object (equivalent of
pmemobj_tx_zalloc)
.IP \[bu] 2
\f[B]POBJ_XALLOC_NO_FLUSH\f[] \- skip flush on commit (when application
deals with flushing or uses pmemobj_memcpy_persist)
.IP \[bu] 2
\f[B]POBJ_CLASS_ID(class_id)\f[] \- allocate the object from the
allocation class with id equal to \f[I]class_id\f[]
.PP
This function must be called during \f[B]TX_STAGE_WORK\f[].
.PP
The \f[B]pmemobj_tx_realloc\f[]() function transactionally resizes an
existing object to the given \f[I]size\f[] and changes its type to
\f[I]type_num\f[].
If \f[I]oid\f[] is \f[B]OID_NULL\f[], then the call is equivalent to
\f[I]pmemobj_tx_alloc(pop, size, type_num)\f[].
If \f[I]size\f[] is equal to zero and \f[I]oid\f[] is not
\f[B]OID_NULL\f[], then the call is equivalent to
\f[I]pmemobj_tx_free(oid)\f[].
If the new size is larger than the old size, the added memory will
\f[I]not\f[] be initialized.
This function must be called during \f[B]TX_STAGE_WORK\f[].
.PP
The \f[B]pmemobj_tx_zrealloc\f[]() function transactionally resizes an
existing object to the given \f[I]size\f[] and changes its type to
\f[I]type_num\f[].
If the new size is larger than the old size, the extended new space is
zeroed.
This function must be called during \f[B]TX_STAGE_WORK\f[].
.PP
The \f[B]pmemobj_tx_strdup\f[]() function transactionally allocates a
new object containing a duplicate of the string \f[I]s\f[] and assigns
it a type \f[I]type_num\f[].
This function must be called during \f[B]TX_STAGE_WORK\f[].
.PP
The \f[B]pmemobj_tx_wcsdup\f[]() function transactionally allocates a
new object containing a duplicate of the wide character string
\f[I]s\f[] and assigns it a type \f[I]type_num\f[].
This function must be called during \f[B]TX_STAGE_WORK\f[].
.PP
The \f[B]pmemobj_tx_free\f[]() function transactionally frees an
existing object referenced by \f[I]oid\f[].
This function must be called during \f[B]TX_STAGE_WORK\f[].
.PP
The \f[B]TX_NEW\f[]() macro transactionally allocates a new object of
given \f[I]TYPE\f[] and assigns it a type number read from the typed
\f[I]OID\f[].
The allocation size is determined from the size of the user\-defined
structure \f[I]TYPE\f[].
If successful and called during \f[B]TX_STAGE_WORK\f[] it returns a
handle to the newly allocated object.
Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[],
\f[B]OID_NULL\f[] is returned, and \f[I]errno\f[] is set appropriately.
.PP
The \f[B]TX_ALLOC\f[]() macro transactionally allocates a new object of
given \f[I]TYPE\f[] and assigns it a type number read from the typed
\f[I]OID\f[].
The allocation size is passed by \f[I]size\f[] parameter.
If successful and called during \f[B]TX_STAGE_WORK\f[] it returns a
handle to the newly allocated object.
Otherwise, the stage is set to \f[B]TX_STAGE_ONABORT\f[],
\f[B]OID_NULL\f[] is returned, and \f[I]errno\f[] is set appropriately.
.PP
The \f[B]TX_ZNEW\f[]() macro transactionally allocates a new zeroed
object of given \f[I]TYPE\f[] and assigns it a type number read from the
typed \f[I]OID\f[].
The allocation size is determined from the size of the user\-defined
structure \f[I]TYPE\f[].
If successful and called during \f[B]TX_STAGE_WORK\f[] it returns a
handle to the newly allocated object.
Otherwise, stage changes to \f[B]TX_STAGE_ONABORT\f[], \f[B]OID_NULL\f[]
is returned, and \f[I]errno\f[] is set appropriately.
.PP
The \f[B]TX_ZALLOC\f[]() macro transactionally allocates a new zeroed
object of given \f[I]TYPE\f[] and assigns it a type number read from the
typed \f[I]OID\f[].
The allocation size is passed by \f[I]size\f[] argument.
If successful and called during \f[B]TX_STAGE_WORK\f[] it returns a
handle to the newly allocated object.
Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[],
\f[B]OID_NULL\f[] is returned, and \f[I]errno\f[] is set appropriately.
.PP
The \f[B]TX_XALLOC\f[]() macro transactionally allocates a new object of
given \f[I]TYPE\f[] and assigns it a type number read from the typed
\f[I]OID\f[].
The allocation size is passed by \f[I]size\f[] argument.
The \f[I]flags\f[] argument is a bitmask of values described in
\f[B]pmemobj_tx_xalloc\f[] section.
If successful and called during \f[B]TX_STAGE_WORK\f[] it returns a
handle to the newly allocated object.
Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[],
\f[B]OID_NULL\f[] is returned, and \f[I]errno\f[] is set appropriately.
.PP
The \f[B]TX_REALLOC\f[]() macro transactionally resizes an existing
object referenced by a handle \f[I]o\f[] to the given \f[I]size\f[].
If successful and called during \f[B]TX_STAGE_WORK\f[] it returns a
handle to the reallocated object.
Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[],
\f[B]OID_NULL\f[] is returned, and \f[I]errno\f[] is set appropriately.
.PP
The \f[B]TX_ZREALLOC\f[]() macro transactionally resizes an existing
object referenced by a handle \f[I]o\f[] to the given \f[I]size\f[].
If the new size is larger than the old size, the extended new space is
zeroed.
If successful and called during \f[B]TX_STAGE_WORK\f[] it returns a
handle to the reallocated object.
Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[],
\f[B]OID_NULL\f[] is returned, and \f[I]errno\f[] is set appropriately.
.PP
The \f[B]TX_STRDUP\f[]() macro transactionally allocates a new object
containing a duplicate of the string \f[I]s\f[] and assigns it type
\f[I]type_num\f[].
If successful and called during \f[B]TX_STAGE_WORK\f[] it returns a
handle to the newly allocated object.
Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[],
\f[B]OID_NULL\f[] is returned, and \f[I]errno\f[] is set appropriately.
.PP
The \f[B]TX_WCSDUP\f[]() macro transactionally allocates a new object
containing a duplicate of the wide character string \f[I]s\f[] and
assigns it a type \f[I]type_num\f[].
If successful and called during \f[B]TX_STAGE_WORK\f[], it returns a
handle to the newly allocated object.
Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[],
\f[B]OID_NULL\f[] is returned, and \f[I]errno\f[] is set appropriately.
.PP
The \f[B]TX_FREE\f[]() macro transactionally frees the memory space
represented by an object handle \f[I]o\f[].
If \f[I]o\f[] is \f[B]OID_NULL\f[], no operation is performed.
If successful and called during \f[B]TX_STAGE_WORK\f[],
\f[B]TX_FREE\f[]() returns 0.
Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[] and an
error number is returned.
.SH RETURN VALUE
.PP
On success, the \f[B]pmemobj_tx_alloc\f[]()
,\f[B]pmemobj_tx_zalloc\f[](), \f[B]pmemobj_tx_xalloc\f[](),
\f[B]pmemobj_tx_strdup\f[]() and \f[B]pmemobj_tx_wcsdup\f[]() functions
return a handle to the newly allocated object.
Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[],
\f[B]OID_NULL\f[] is returned, and \f[I]errno\f[] is set appropriately.
If \f[I]size\f[] equals 0, \f[B]OID_NULL\f[] is returned and
\f[I]errno\f[] is set appropriately.
.PP
On success, \f[B]pmemobj_tx_realloc\f[]() and
\f[B]pmemobj_tx_zrealloc\f[]() return a handle to the resized object.
Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[],
\f[B]OID_NULL\f[] is returned, and \f[I]errno\f[] is set appropriately.
Note that the object handle value may change as a result of
reallocation.
.PP
On success, \f[B]pmemobj_tx_free\f[]() returns 0.
Otherwise, the stage is set to \f[B]TX_STAGE_ONABORT\f[] and an error
number is returned.
.SH SEE ALSO
.PP
\f[B]pmemobj_tx_add_range\f[](3), **pmemobj_tx_begin*(3),
\f[B]libpmemobj\f[](7) and \f[B]<http://pmem.io>\f[]