Provided by: libpmemobj-dev_1.12.1-2_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>