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>