Provided by: libpmemobj-dev_1.13.1-1.1ubuntu2_amd64 
NAME
pmemobj_tx_alloc(), pmemobj_tx_zalloc(), pmemobj_tx_xalloc(), pmemobj_tx_realloc(),
pmemobj_tx_zrealloc(), pmemobj_tx_strdup(), pmemobj_tx_xstrdup(), pmemobj_tx_wcsdup(),
pmemobj_tx_xwcsdup(), pmemobj_tx_free(), pmemobj_tx_xfree()
TX_NEW(), TX_ALLOC(), TX_ZNEW(), TX_ZALLOC(), TX_XALLOC(), TX_REALLOC(), TX_ZREALLOC(), TX_STRDUP(),
TX_XSTRDUP(), TX_WCSDUP(), TX_XWCSDUP(), TX_FREE(), TX_XFREE() - transactional object manipulation
SYNOPSIS
#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);
int pmemobj_tx_xfree(PMEMoid oid, uint64_t flags);
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)
TX_XFREE(TOID o, uint64_t flags)
DESCRIPTION
The pmemobj_tx_alloc() function transactionally allocates a new object of given size and type_num. In
contrast to the non-transactional allocations, the objects are added to the internal object containers of
given type_num only after the transaction is committed, making the objects visible to the
POBJ_FOREACH_*() macros. This function must be called during TX_STAGE_WORK.
The pmemobj_tx_zalloc() function transactionally allocates a new zeroed object of given size and
type_num. This function must be called during TX_STAGE_WORK.
The pmemobj_tx_xalloc() function transactionally allocates a new object of given size and type_num. The
flags argument is a bitmask of the following values:
• POBJ_XALLOC_ZERO - zero the allocated object (equivalent of pmemobj_tx_zalloc)
• POBJ_XALLOC_NO_FLUSH - skip flush on commit (when application deals with flushing or uses
pmemobj_memcpy_persist)
• POBJ_CLASS_ID(class_id) - allocate an object from the allocation class with id equal to class_id
• POBJ_ARENA_ID(arena_id) - allocate an object from the arena specified by arena_id. The arena must
exist, otherwise, the behavior is undefined. If arena_id is equal 0, then arena assigned to the
current thread will be used.
• POBJ_XALLOC_NO_ABORT - if the function does not end successfully, do not abort the transaction.
This function must be called during TX_STAGE_WORK.
The pmemobj_tx_realloc() function transactionally resizes an existing object to the given size and
changes its type to type_num. If oid is OID_NULL, then the call is equivalent to pmemobj_tx_alloc(pop,
size, type_num). If size is equal to zero and oid is not OID_NULL, then the call is equivalent to
pmemobj_tx_free(oid). If the new size is larger than the old size, the added memory will not be
initialized. This function must be called during TX_STAGE_WORK.
The pmemobj_tx_zrealloc() function transactionally resizes an existing object to the given size and
changes its type to type_num. If the new size is larger than the old size, the extended new space is
zeroed. This function must be called during TX_STAGE_WORK.
The pmemobj_tx_strdup() function transactionally allocates a new object containing a duplicate of the
string s and assigns it a type type_num. This function must be called during TX_STAGE_WORK.
The pmemobj_tx_xstrdup() function behaves exactly the same as pmemobj_tx_strdup() when flags equals zero.
The flags argument is a bitmask of values described in pmemobj_tx_xalloc section.
The pmemobj_tx_wcsdup() function transactionally allocates a new object containing a duplicate of the
wide character string s and assigns it a type type_num. This function must be called during
TX_STAGE_WORK.
The pmemobj_tx_xwcsdup() function behaves exactly the same as pmemobj_tx_wcsdup() when flags equals zero.
The flags argument is a bitmask of values described in pmemobj_tx_xalloc section.
The pmemobj_tx_free() function transactionally frees an existing object referenced by oid. This function
must be called during TX_STAGE_WORK.
The pmemobj_tx_xfree() function behaves exactly the same as pmemobj_tx_free() when flags equals zero.
flags is a bitmask of the following value:
• POBJ_XFREE_NO_ABORT - if the function does not end successfully, do not abort the transaction.
This function must be called during TX_STAGE_WORK.
The TX_NEW() macro transactionally allocates a new object of given TYPE and assigns it a type number read
from the typed OID. The allocation size is determined from the size of the user-defined structure TYPE.
If successful and called during TX_STAGE_WORK it returns a handle to the newly allocated object.
Otherwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL is returned, and errno is set
appropriately.
The TX_ALLOC() macro transactionally allocates a new object of given TYPE and assigns it a type number
read from the typed OID. The allocation size is passed by size parameter. If successful and called
during TX_STAGE_WORK it returns a handle to the newly allocated object. Otherwise, the stage is set to
TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately.
The TX_ZNEW() macro transactionally allocates a new zeroed object of given TYPE and assigns it a type
number read from the typed OID. The allocation size is determined from the size of the user-defined
structure TYPE. If successful and called during TX_STAGE_WORK it returns a handle to the newly allocated
object. Otherwise, stage changes to TX_STAGE_ONABORT, OID_NULL is returned, and errno is set
appropriately.
The TX_ZALLOC() macro transactionally allocates a new zeroed object of given TYPE and assigns it a type
number read from the typed OID. The allocation size is passed by size argument. If successful and
called during TX_STAGE_WORK it returns a handle to the newly allocated object. Otherwise, the stage is
changed to TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately.
The TX_XALLOC() macro transactionally allocates a new object of given TYPE and assigns it a type number
read from the typed OID. The allocation size is passed by size argument. The flags argument is a
bitmask of values described in pmemobj_tx_xalloc section. If successful and called during TX_STAGE_WORK
it returns a handle to the newly allocated object. Otherwise, the OID_NULL is returned, errno is set and
when flags do not contain POBJ_XALLOC_NO_ABORT, the transaction is aborted.
The TX_REALLOC() macro transactionally resizes an existing object referenced by a handle o to the given
size. If successful and called during TX_STAGE_WORK it returns a handle to the reallocated object.
Otherwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL is returned, and errno is set
appropriately.
The TX_ZREALLOC() macro transactionally resizes an existing object referenced by a handle o to the given
size. If the new size is larger than the old size, the extended new space is zeroed. If successful and
called during TX_STAGE_WORK it returns a handle to the reallocated object. Otherwise, the stage is
changed to TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately.
The TX_STRDUP() macro transactionally allocates a new object containing a duplicate of the string s and
assigns it type type_num. If successful and called during TX_STAGE_WORK it returns a handle to the newly
allocated object. Otherwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL is returned, and errno
is set appropriately.
The TX_XSTRDUP() macro transactionally allocates a new object containing a duplicate of the string s and
assigns it type type_num. The flags argument is a bitmask of values described in pmemobj_tx_xalloc
section. If successful and called during TX_STAGE_WORK it returns a handle to the newly allocated
object. Otherwise, the OID_NULL is returned, errno is set and when flags do not contain
POBJ_XALLOC_NO_ABORT, the transaction is aborted.
The TX_WCSDUP() macro transactionally allocates a new object containing a duplicate of the wide character
string s and assigns it a type type_num. If successful and called during TX_STAGE_WORK, it returns a
handle to the newly allocated object. Otherwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL is
returned, and errno is set appropriately.
The TX_XWCSDUP() macro transactionally allocates a new object containing a duplicate of the wide
character string s and assigns it a type type_num. The flags argument is a bitmask of values described
in pmemobj_tx_xalloc section. If successful and called during TX_STAGE_WORK it returns a handle to the
newly allocated object. Otherwise, the OID_NULL is returned, errno is set and when flags do not contain
POBJ_XALLOC_NO_ABORT, the transaction is aborted.
The TX_FREE() macro transactionally frees the memory space represented by an object handle o. If o is
OID_NULL, no operation is performed. If successful and called during TX_STAGE_WORK, TX_FREE() returns 0.
Otherwise, the stage is changed to TX_STAGE_ONABORT and errno is set appropriately.
The TX_XFREE() macro transactionally frees the memory space represented by an object handle o. If o is
OID_NULL, no operation is performed. The flags argument is a bitmask of values described in
pmemobj_tx_xfree section. If successful and called during TX_STAGE_WORK, TX_FREE() returns 0.
Otherwise, the error number is returned, errno is set and when flags do not contain POBJ_XFREE_NO_ABORT,
the transaction is aborted.
RETURN VALUE
On success, the pmemobj_tx_alloc(), pmemobj_tx_zalloc(), pmemobj_tx_strdup() and pmemobj_tx_wcsdup()
functions return a handle to the newly allocated object. Otherwise, the stage is changed to
TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately. If size equals 0, OID_NULL is
returned and errno is set appropriately.
On success, the pmemobj_tx_xalloc(), pmemobj_tx_xstrdup() and pmemobj_tx_xwcsdup() functions return a
handle to the newly allocated object. Otherwise, the OID_NULL is returned, errno is set and when flags
do not contain POBJ_XALLOC_NO_ABORT, the transaction is aborted.
On success, pmemobj_tx_realloc() and pmemobj_tx_zrealloc() return a handle to the resized object.
Otherwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL is returned, and errno is set
appropriately. Note that the object handle value may change as a result of reallocation.
On success, pmemobj_tx_free() returns 0. Otherwise, the stage is changed to TX_STAGE_ONABORT, errno is
set appropriately and transaction is aborted
On success pmemobj_tx_xfree() returns 0. Otherwise, the error number is returned, errno is set and when
flags do not contain POBJ_XFREE_NO_ABORT, the transaction is aborted.
SEE ALSO
pmemobj_tx_add_range(3), pmemobj_tx_begin(3), libpmemobj(7) and <https://pmem.io>