Provided by: libpmemobj-dev_1.13.1-1.1ubuntu2_amd64 bug

NAME

       pmemobj_tx_alloc(),  pmemobj_tx_zalloc(),  pmemobj_tx_xalloc(),  pmemobj_tx_realloc(),  pmemobj_tx_zreal‐
       loc(),  pmemobj_tx_strdup(),  pmemobj_tx_xstrdup(),  pmemobj_tx_wcsdup(),  pmemobj_tx_xwcsdup(),   pmemo‐
       bj_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_FORE‐
       ACH_*() 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_mem‐
         cpy_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 ex‐
         ist, 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 pmemo‐
       bj_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 ze‐
       roed.  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.   Other‐
       wise, 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 dur‐
       ing 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 appropri‐
       ately.

       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  bit‐
       mask  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.  Oth‐
       erwise, 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  sec‐
       tion.   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  charac‐
       ter  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 new‐
       ly 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 pmemo‐
       bj_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_ON‐
       ABORT,  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.  Other‐
       wise, 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>