Provided by: libpmemobj-dev_1.8-1ubuntu1_amd64 bug

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_idPOBJ_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>