.\" Automatically generated by Pandoc 2.10.1 .\" .TH "PMEMOBJ_TX_ALLOC" "3" "2020-10-28" "PMDK - pmemobj API version 2.3" "PMDK Programmer's Manual" .hy .\" SPDX-License-Identifier: BSD-3-Clause .\" Copyright 2017-2019, Intel Corporation .SH NAME .PP \f[B]pmemobj_tx_alloc\f[R](), \f[B]pmemobj_tx_zalloc\f[R](), \f[B]pmemobj_tx_xalloc\f[R](), \f[B]pmemobj_tx_realloc\f[R](), \f[B]pmemobj_tx_zrealloc\f[R](), \f[B]pmemobj_tx_strdup\f[R](), \f[B]pmemobj_tx_xstrdup\f[R](), \f[B]pmemobj_tx_wcsdup\f[R](), \f[B]pmemobj_tx_xwcsdup\f[R](), \f[B]pmemobj_tx_free\f[R](), \f[B]pmemobj_tx_xfree\f[R]() .PP \f[B]TX_NEW\f[R](), \f[B]TX_ALLOC\f[R](), \f[B]TX_ZNEW\f[R](), \f[B]TX_ZALLOC\f[R](), \f[B]TX_XALLOC\f[R](), \f[B]TX_REALLOC\f[R](), \f[B]TX_ZREALLOC\f[R](), \f[B]TX_STRDUP\f[R](), \f[B]TX_XSTRDUP\f[R](), \f[B]TX_WCSDUP\f[R](), \f[B]TX_XWCSDUP\f[R](), \f[B]TX_FREE\f[R](), \f[B]TX_XFREE\f[R]() - transactional object manipulation .SH SYNOPSIS .IP .nf \f[C] #include 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) \f[R] .fi .SH DESCRIPTION .PP The \f[B]pmemobj_tx_alloc\f[R]() function transactionally allocates a new object of given \f[I]size\f[R] and \f[I]type_num\f[R]. In contrast to the non-transactional allocations, the objects are added to the internal object containers of given \f[I]type_num\f[R] only after the transaction is committed, making the objects visible to the \f[B]POBJ_FOREACH_*\f[R]() macros. This function must be called during \f[B]TX_STAGE_WORK\f[R]. .PP The \f[B]pmemobj_tx_zalloc\f[R]() function transactionally allocates a new zeroed object of given \f[I]size\f[R] and \f[I]type_num\f[R]. This function must be called during \f[B]TX_STAGE_WORK\f[R]. .PP The \f[B]pmemobj_tx_xalloc\f[R]() function transactionally allocates a new object of given \f[I]size\f[R] and \f[I]type_num\f[R]. The \f[I]flags\f[R] argument is a bitmask of the following values: .IP \[bu] 2 \f[B]POBJ_XALLOC_ZERO\f[R] - zero the allocated object (equivalent of pmemobj_tx_zalloc) .IP \[bu] 2 \f[B]POBJ_XALLOC_NO_FLUSH\f[R] - skip flush on commit (when application deals with flushing or uses pmemobj_memcpy_persist) .IP \[bu] 2 \f[B]POBJ_CLASS_ID(class_id)\f[R] - allocate an object from the allocation class with id equal to \f[I]class_id\f[R] .IP \[bu] 2 \f[B]POBJ_ARENA_ID(arena_id)\f[R] - allocate an object from the arena specified by \f[I]arena_id\f[R]. The arena must exist, otherwise, the behavior is undefined. If \f[I]arena_id\f[R] is equal 0, then arena assigned to the current thread will be used. .IP \[bu] 2 \f[B]POBJ_XALLOC_NO_ABORT\f[R] - if the function does not end successfully, do not abort the transaction. .PP This function must be called during \f[B]TX_STAGE_WORK\f[R]. .PP The \f[B]pmemobj_tx_realloc\f[R]() function transactionally resizes an existing object to the given \f[I]size\f[R] and changes its type to \f[I]type_num\f[R]. If \f[I]oid\f[R] is \f[B]OID_NULL\f[R], then the call is equivalent to \f[I]pmemobj_tx_alloc(pop, size, type_num)\f[R]. If \f[I]size\f[R] is equal to zero and \f[I]oid\f[R] is not \f[B]OID_NULL\f[R], then the call is equivalent to \f[I]pmemobj_tx_free(oid)\f[R]. If the new size is larger than the old size, the added memory will \f[I]not\f[R] be initialized. This function must be called during \f[B]TX_STAGE_WORK\f[R]. .PP The \f[B]pmemobj_tx_zrealloc\f[R]() function transactionally resizes an existing object to the given \f[I]size\f[R] and changes its type to \f[I]type_num\f[R]. If the new size is larger than the old size, the extended new space is zeroed. This function must be called during \f[B]TX_STAGE_WORK\f[R]. .PP The \f[B]pmemobj_tx_strdup\f[R]() function transactionally allocates a new object containing a duplicate of the string \f[I]s\f[R] and assigns it a type \f[I]type_num\f[R]. This function must be called during \f[B]TX_STAGE_WORK\f[R]. .PP The \f[B]pmemobj_tx_xstrdup\f[R]() function behaves exactly the same as \f[B]pmemobj_tx_strdup\f[R]() when \f[I]flags\f[R] equals zero. The \f[I]flags\f[R] argument is a bitmask of values described in \f[B]pmemobj_tx_xalloc\f[R] section. .PP The \f[B]pmemobj_tx_wcsdup\f[R]() function transactionally allocates a new object containing a duplicate of the wide character string \f[I]s\f[R] and assigns it a type \f[I]type_num\f[R]. This function must be called during \f[B]TX_STAGE_WORK\f[R]. .PP The \f[B]pmemobj_tx_xwcsdup\f[R]() function behaves exactly the same as \f[B]pmemobj_tx_wcsdup\f[R]() when \f[I]flags\f[R] equals zero. The \f[I]flags\f[R] argument is a bitmask of values described in \f[B]pmemobj_tx_xalloc\f[R] section. .PP The \f[B]pmemobj_tx_free\f[R]() function transactionally frees an existing object referenced by \f[I]oid\f[R]. This function must be called during \f[B]TX_STAGE_WORK\f[R]. .PP The \f[B]pmemobj_tx_xfree\f[R]() function behaves exactly the same as \f[B]pmemobj_tx_free\f[R]() when \f[I]flags\f[R] equals zero. \f[I]flags\f[R] is a bitmask of the following value: .IP \[bu] 2 \f[B]POBJ_XFREE_NO_ABORT\f[R] - if the function does not end successfully, do not abort the transaction. .PP This function must be called during \f[B]TX_STAGE_WORK\f[R]. .PP The \f[B]TX_NEW\f[R]() macro transactionally allocates a new object of given \f[I]TYPE\f[R] and assigns it a type number read from the typed \f[I]OID\f[R]. The allocation size is determined from the size of the user-defined structure \f[I]TYPE\f[R]. If successful and called during \f[B]TX_STAGE_WORK\f[R] it returns a handle to the newly allocated object. Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[R], \f[B]OID_NULL\f[R] is returned, and \f[I]errno\f[R] is set appropriately. .PP The \f[B]TX_ALLOC\f[R]() macro transactionally allocates a new object of given \f[I]TYPE\f[R] and assigns it a type number read from the typed \f[I]OID\f[R]. The allocation size is passed by \f[I]size\f[R] parameter. If successful and called during \f[B]TX_STAGE_WORK\f[R] it returns a handle to the newly allocated object. Otherwise, the stage is set to \f[B]TX_STAGE_ONABORT\f[R], \f[B]OID_NULL\f[R] is returned, and \f[I]errno\f[R] is set appropriately. .PP The \f[B]TX_ZNEW\f[R]() macro transactionally allocates a new zeroed object of given \f[I]TYPE\f[R] and assigns it a type number read from the typed \f[I]OID\f[R]. The allocation size is determined from the size of the user-defined structure \f[I]TYPE\f[R]. If successful and called during \f[B]TX_STAGE_WORK\f[R] it returns a handle to the newly allocated object. Otherwise, stage changes to \f[B]TX_STAGE_ONABORT\f[R], \f[B]OID_NULL\f[R] is returned, and \f[I]errno\f[R] is set appropriately. .PP The \f[B]TX_ZALLOC\f[R]() macro transactionally allocates a new zeroed object of given \f[I]TYPE\f[R] and assigns it a type number read from the typed \f[I]OID\f[R]. The allocation size is passed by \f[I]size\f[R] argument. If successful and called during \f[B]TX_STAGE_WORK\f[R] it returns a handle to the newly allocated object. Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[R], \f[B]OID_NULL\f[R] is returned, and \f[I]errno\f[R] is set appropriately. .PP The \f[B]TX_XALLOC\f[R]() macro transactionally allocates a new object of given \f[I]TYPE\f[R] and assigns it a type number read from the typed \f[I]OID\f[R]. The allocation size is passed by \f[I]size\f[R] argument. The \f[I]flags\f[R] argument is a bitmask of values described in \f[B]pmemobj_tx_xalloc\f[R] section. If successful and called during \f[B]TX_STAGE_WORK\f[R] it returns a handle to the newly allocated object. Otherwise, the \f[B]OID_NULL\f[R] is returned, \f[B]errno\f[R] is set and when flags do not contain \f[B]POBJ_XALLOC_NO_ABORT\f[R], the transaction is aborted. .PP The \f[B]TX_REALLOC\f[R]() macro transactionally resizes an existing object referenced by a handle \f[I]o\f[R] to the given \f[I]size\f[R]. If successful and called during \f[B]TX_STAGE_WORK\f[R] it returns a handle to the reallocated object. Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[R], \f[B]OID_NULL\f[R] is returned, and \f[I]errno\f[R] is set appropriately. .PP The \f[B]TX_ZREALLOC\f[R]() macro transactionally resizes an existing object referenced by a handle \f[I]o\f[R] to the given \f[I]size\f[R]. If the new size is larger than the old size, the extended new space is zeroed. If successful and called during \f[B]TX_STAGE_WORK\f[R] it returns a handle to the reallocated object. Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[R], \f[B]OID_NULL\f[R] is returned, and \f[I]errno\f[R] is set appropriately. .PP The \f[B]TX_STRDUP\f[R]() macro transactionally allocates a new object containing a duplicate of the string \f[I]s\f[R] and assigns it type \f[I]type_num\f[R]. If successful and called during \f[B]TX_STAGE_WORK\f[R] it returns a handle to the newly allocated object. Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[R], \f[B]OID_NULL\f[R] is returned, and \f[I]errno\f[R] is set appropriately. .PP The \f[B]TX_XSTRDUP\f[R]() macro transactionally allocates a new object containing a duplicate of the string \f[I]s\f[R] and assigns it type \f[I]type_num\f[R]. The \f[I]flags\f[R] argument is a bitmask of values described in \f[B]pmemobj_tx_xalloc\f[R] section. If successful and called during \f[B]TX_STAGE_WORK\f[R] it returns a handle to the newly allocated object. Otherwise, the \f[B]OID_NULL\f[R] is returned, \f[B]errno\f[R] is set and when flags do not contain \f[B]POBJ_XALLOC_NO_ABORT\f[R], the transaction is aborted. .PP The \f[B]TX_WCSDUP\f[R]() macro transactionally allocates a new object containing a duplicate of the wide character string \f[I]s\f[R] and assigns it a type \f[I]type_num\f[R]. If successful and called during \f[B]TX_STAGE_WORK\f[R], it returns a handle to the newly allocated object. Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[R], \f[B]OID_NULL\f[R] is returned, and \f[I]errno\f[R] is set appropriately. .PP The \f[B]TX_XWCSDUP\f[R]() macro transactionally allocates a new object containing a duplicate of the wide character string \f[I]s\f[R] and assigns it a type \f[I]type_num\f[R]. The \f[I]flags\f[R] argument is a bitmask of values described in \f[B]pmemobj_tx_xalloc\f[R] section. If successful and called during \f[B]TX_STAGE_WORK\f[R] it returns a handle to the newly allocated object. Otherwise, the \f[B]OID_NULL\f[R] is returned, \f[B]errno\f[R] is set and when flags do not contain \f[B]POBJ_XALLOC_NO_ABORT\f[R], the transaction is aborted. .PP The \f[B]TX_FREE\f[R]() macro transactionally frees the memory space represented by an object handle \f[I]o\f[R]. If \f[I]o\f[R] is \f[B]OID_NULL\f[R], no operation is performed. If successful and called during \f[B]TX_STAGE_WORK\f[R], \f[B]TX_FREE\f[R]() returns 0. Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[R] and \f[I]errno\f[R] is set appropriately. .PP The \f[B]TX_XFREE\f[R]() macro transactionally frees the memory space represented by an object handle \f[I]o\f[R]. If \f[I]o\f[R] is \f[B]OID_NULL\f[R], no operation is performed. The \f[I]flags\f[R] argument is a bitmask of values described in \f[B]pmemobj_tx_xfree\f[R] section. If successful and called during \f[B]TX_STAGE_WORK\f[R], \f[B]TX_FREE\f[R]() returns 0. Otherwise, the error number is returned, \f[B]errno\f[R] is set and when flags do not contain \f[B]POBJ_XFREE_NO_ABORT\f[R], the transaction is aborted. .SH RETURN VALUE .PP On success, the \f[B]pmemobj_tx_alloc\f[R](), \f[B]pmemobj_tx_zalloc\f[R](), \f[B]pmemobj_tx_strdup\f[R]() and \f[B]pmemobj_tx_wcsdup\f[R]() functions return a handle to the newly allocated object. Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[R], \f[B]OID_NULL\f[R] is returned, and \f[I]errno\f[R] is set appropriately. If \f[I]size\f[R] equals 0, \f[B]OID_NULL\f[R] is returned and \f[I]errno\f[R] is set appropriately. .PP On success, the \f[B]pmemobj_tx_xalloc\f[R](), \f[B]pmemobj_tx_xstrdup\f[R]() and \f[B]pmemobj_tx_xwcsdup\f[R]() functions return a handle to the newly allocated object. Otherwise, the \f[B]OID_NULL\f[R] is returned, \f[B]errno\f[R] is set and when flags do not contain \f[B]POBJ_XALLOC_NO_ABORT\f[R], the transaction is aborted. .PP On success, \f[B]pmemobj_tx_realloc\f[R]() and \f[B]pmemobj_tx_zrealloc\f[R]() return a handle to the resized object. Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[R], \f[B]OID_NULL\f[R] is returned, and \f[I]errno\f[R] is set appropriately. Note that the object handle value may change as a result of reallocation. .PP On success, \f[B]pmemobj_tx_free\f[R]() returns 0. Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[R], \f[B]errno\f[R] is set appropriately and transaction is aborted .PP On success \f[B]pmemobj_tx_xfree\f[R]() returns 0. Otherwise, the error number is returned, \f[B]errno\f[R] is set and when flags do not contain \f[B]POBJ_XFREE_NO_ABORT\f[R], the transaction is aborted. .SH SEE ALSO .PP \f[B]pmemobj_tx_add_range\f[R](3), \f[B]pmemobj_tx_begin\f[R](3), \f[B]libpmemobj\f[R](7) and \f[B]\f[R]