NAME

       pmemobj_tx_alloc(),    pmemobj_tx_zalloc(),   pmemobj_tx_xalloc(),   pmemobj_tx_realloc(),
       pmemobj_tx_zrealloc(), pmemobj_tx_strdup(), pmemobj_tx_wcsdup(), pmemobj_tx_free(),

       TX_NEW(), TX_ALLOC(), TX_ZNEW(), TX_ZALLOC(),  TX_XALLOC(),  TX_REALLOC(),  TX_ZREALLOC(),
       TX_STRDUP(), TX_WCSDUP(), TX_FREE() - 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);

              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)

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 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 the object from the allocation class with id equal to
         class_id

       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_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_free() function transactionally frees an existing object referenced by oid.
       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  stage is changed to TX_STAGE_ONABORT, OID_NULL is returned, and
       errno is set appropriately.

       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_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_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 an error number is returned.

RETURN VALUE

       On   success,   the    pmemobj_tx_alloc()    ,pmemobj_tx_zalloc(),    pmemobj_tx_xalloc(),
       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, 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 set to TX_STAGE_ONABORT
       and an error number is returned.

SEE ALSO

       pmemobj_tx_add_range(3), **pmemobj_tx_begin*(3), libpmemobj(7) and <http://pmem.io>