.\" Automatically generated by Pandoc 2.0.6 .\" .TH "PMEMOBJ_TX_ALLOC" "3" "2022-08-25" "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[](), \f[B]pmemobj_tx_zalloc\f[](), \f[B]pmemobj_tx_xalloc\f[](), \f[B]pmemobj_tx_realloc\f[](), \f[B]pmemobj_tx_zrealloc\f[](), \f[B]pmemobj_tx_strdup\f[](), \f[B]pmemobj_tx_xstrdup\f[](), \f[B]pmemobj_tx_wcsdup\f[](), \f[B]pmemobj_tx_xwcsdup\f[](), \f[B]pmemobj_tx_free\f[](), \f[B]pmemobj_tx_xfree\f[]() .PP \f[B]TX_NEW\f[](), \f[B]TX_ALLOC\f[](), \f[B]TX_ZNEW\f[](), \f[B]TX_ZALLOC\f[](), \f[B]TX_XALLOC\f[](), \f[B]TX_REALLOC\f[](), \f[B]TX_ZREALLOC\f[](), \f[B]TX_STRDUP\f[](), \f[B]TX_XSTRDUP\f[](), \f[B]TX_WCSDUP\f[](), \f[B]TX_XWCSDUP\f[](), \f[B]TX_FREE\f[](), \f[B]TX_XFREE\f[]() \- 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[] .fi .SH DESCRIPTION .PP The \f[B]pmemobj_tx_alloc\f[]() function transactionally allocates a new object of given \f[I]size\f[] and \f[I]type_num\f[]. In contrast to the non\-transactional allocations, the objects are added to the internal object containers of given \f[I]type_num\f[] only after the transaction is committed, making the objects visible to the \f[B]POBJ_FOREACH_*\f[]() macros. This function must be called during \f[B]TX_STAGE_WORK\f[]. .PP The \f[B]pmemobj_tx_zalloc\f[]() function transactionally allocates a new zeroed object of given \f[I]size\f[] and \f[I]type_num\f[]. This function must be called during \f[B]TX_STAGE_WORK\f[]. .PP The \f[B]pmemobj_tx_xalloc\f[]() function transactionally allocates a new object of given \f[I]size\f[] and \f[I]type_num\f[]. The \f[I]flags\f[] argument is a bitmask of the following values: .IP \[bu] 2 \f[B]POBJ_XALLOC_ZERO\f[] \- zero the allocated object (equivalent of pmemobj_tx_zalloc) .IP \[bu] 2 \f[B]POBJ_XALLOC_NO_FLUSH\f[] \- 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[] \- allocate an object from the allocation class with id equal to \f[I]class_id\f[] .IP \[bu] 2 \f[B]POBJ_ARENA_ID(arena_id)\f[] \- allocate an object from the arena specified by \f[I]arena_id\f[]. The arena must exist, otherwise, the behavior is undefined. If \f[I]arena_id\f[] is equal 0, then arena assigned to the current thread will be used. .IP \[bu] 2 \f[B]POBJ_XALLOC_NO_ABORT\f[] \- 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[]. .PP The \f[B]pmemobj_tx_realloc\f[]() function transactionally resizes an existing object to the given \f[I]size\f[] and changes its type to \f[I]type_num\f[]. If \f[I]oid\f[] is \f[B]OID_NULL\f[], then the call is equivalent to \f[I]pmemobj_tx_alloc(pop, size, type_num)\f[]. If \f[I]size\f[] is equal to zero and \f[I]oid\f[] is not \f[B]OID_NULL\f[], then the call is equivalent to \f[I]pmemobj_tx_free(oid)\f[]. If the new size is larger than the old size, the added memory will \f[I]not\f[] be initialized. This function must be called during \f[B]TX_STAGE_WORK\f[]. .PP The \f[B]pmemobj_tx_zrealloc\f[]() function transactionally resizes an existing object to the given \f[I]size\f[] and changes its type to \f[I]type_num\f[]. 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[]. .PP The \f[B]pmemobj_tx_strdup\f[]() function transactionally allocates a new object containing a duplicate of the string \f[I]s\f[] and assigns it a type \f[I]type_num\f[]. This function must be called during \f[B]TX_STAGE_WORK\f[]. .PP The \f[B]pmemobj_tx_xstrdup\f[]() function behaves exactly the same as \f[B]pmemobj_tx_strdup\f[]() when \f[I]flags\f[] equals zero. The \f[I]flags\f[] argument is a bitmask of values described in \f[B]pmemobj_tx_xalloc\f[] section. .PP The \f[B]pmemobj_tx_wcsdup\f[]() function transactionally allocates a new object containing a duplicate of the wide character string \f[I]s\f[] and assigns it a type \f[I]type_num\f[]. This function must be called during \f[B]TX_STAGE_WORK\f[]. .PP The \f[B]pmemobj_tx_xwcsdup\f[]() function behaves exactly the same as \f[B]pmemobj_tx_wcsdup\f[]() when \f[I]flags\f[] equals zero. The \f[I]flags\f[] argument is a bitmask of values described in \f[B]pmemobj_tx_xalloc\f[] section. .PP The \f[B]pmemobj_tx_free\f[]() function transactionally frees an existing object referenced by \f[I]oid\f[]. This function must be called during \f[B]TX_STAGE_WORK\f[]. .PP The \f[B]pmemobj_tx_xfree\f[]() function behaves exactly the same as \f[B]pmemobj_tx_free\f[]() when \f[I]flags\f[] equals zero. \f[I]flags\f[] is a bitmask of the following value: .IP \[bu] 2 \f[B]POBJ_XFREE_NO_ABORT\f[] \- 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[]. .PP The \f[B]TX_NEW\f[]() macro transactionally allocates a new object of given \f[I]TYPE\f[] and assigns it a type number read from the typed \f[I]OID\f[]. The allocation size is determined from the size of the user\-defined structure \f[I]TYPE\f[]. If successful and called during \f[B]TX_STAGE_WORK\f[] it returns a handle to the newly allocated object. Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[], \f[B]OID_NULL\f[] is returned, and \f[I]errno\f[] is set appropriately. .PP The \f[B]TX_ALLOC\f[]() macro transactionally allocates a new object of given \f[I]TYPE\f[] and assigns it a type number read from the typed \f[I]OID\f[]. The allocation size is passed by \f[I]size\f[] parameter. If successful and called during \f[B]TX_STAGE_WORK\f[] it returns a handle to the newly allocated object. Otherwise, the stage is set to \f[B]TX_STAGE_ONABORT\f[], \f[B]OID_NULL\f[] is returned, and \f[I]errno\f[] is set appropriately. .PP The \f[B]TX_ZNEW\f[]() macro transactionally allocates a new zeroed object of given \f[I]TYPE\f[] and assigns it a type number read from the typed \f[I]OID\f[]. The allocation size is determined from the size of the user\-defined structure \f[I]TYPE\f[]. If successful and called during \f[B]TX_STAGE_WORK\f[] it returns a handle to the newly allocated object. Otherwise, stage changes to \f[B]TX_STAGE_ONABORT\f[], \f[B]OID_NULL\f[] is returned, and \f[I]errno\f[] is set appropriately. .PP The \f[B]TX_ZALLOC\f[]() macro transactionally allocates a new zeroed object of given \f[I]TYPE\f[] and assigns it a type number read from the typed \f[I]OID\f[]. The allocation size is passed by \f[I]size\f[] argument. If successful and called during \f[B]TX_STAGE_WORK\f[] it returns a handle to the newly allocated object. Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[], \f[B]OID_NULL\f[] is returned, and \f[I]errno\f[] is set appropriately. .PP The \f[B]TX_XALLOC\f[]() macro transactionally allocates a new object of given \f[I]TYPE\f[] and assigns it a type number read from the typed \f[I]OID\f[]. The allocation size is passed by \f[I]size\f[] argument. The \f[I]flags\f[] argument is a bitmask of values described in \f[B]pmemobj_tx_xalloc\f[] section. If successful and called during \f[B]TX_STAGE_WORK\f[] it returns a handle to the newly allocated object. Otherwise, the \f[B]OID_NULL\f[] is returned, \f[B]errno\f[] is set and when flags do not contain \f[B]POBJ_XALLOC_NO_ABORT\f[], the transaction is aborted. .PP The \f[B]TX_REALLOC\f[]() macro transactionally resizes an existing object referenced by a handle \f[I]o\f[] to the given \f[I]size\f[]. If successful and called during \f[B]TX_STAGE_WORK\f[] it returns a handle to the reallocated object. Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[], \f[B]OID_NULL\f[] is returned, and \f[I]errno\f[] is set appropriately. .PP The \f[B]TX_ZREALLOC\f[]() macro transactionally resizes an existing object referenced by a handle \f[I]o\f[] to the given \f[I]size\f[]. 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[] it returns a handle to the reallocated object. Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[], \f[B]OID_NULL\f[] is returned, and \f[I]errno\f[] is set appropriately. .PP The \f[B]TX_STRDUP\f[]() macro transactionally allocates a new object containing a duplicate of the string \f[I]s\f[] and assigns it type \f[I]type_num\f[]. If successful and called during \f[B]TX_STAGE_WORK\f[] it returns a handle to the newly allocated object. Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[], \f[B]OID_NULL\f[] is returned, and \f[I]errno\f[] is set appropriately. .PP The \f[B]TX_XSTRDUP\f[]() macro transactionally allocates a new object containing a duplicate of the string \f[I]s\f[] and assigns it type \f[I]type_num\f[]. The \f[I]flags\f[] argument is a bitmask of values described in \f[B]pmemobj_tx_xalloc\f[] section. If successful and called during \f[B]TX_STAGE_WORK\f[] it returns a handle to the newly allocated object. Otherwise, the \f[B]OID_NULL\f[] is returned, \f[B]errno\f[] is set and when flags do not contain \f[B]POBJ_XALLOC_NO_ABORT\f[], the transaction is aborted. .PP The \f[B]TX_WCSDUP\f[]() macro transactionally allocates a new object containing a duplicate of the wide character string \f[I]s\f[] and assigns it a type \f[I]type_num\f[]. If successful and called during \f[B]TX_STAGE_WORK\f[], it returns a handle to the newly allocated object. Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[], \f[B]OID_NULL\f[] is returned, and \f[I]errno\f[] is set appropriately. .PP The \f[B]TX_XWCSDUP\f[]() macro transactionally allocates a new object containing a duplicate of the wide character string \f[I]s\f[] and assigns it a type \f[I]type_num\f[]. The \f[I]flags\f[] argument is a bitmask of values described in \f[B]pmemobj_tx_xalloc\f[] section. If successful and called during \f[B]TX_STAGE_WORK\f[] it returns a handle to the newly allocated object. Otherwise, the \f[B]OID_NULL\f[] is returned, \f[B]errno\f[] is set and when flags do not contain \f[B]POBJ_XALLOC_NO_ABORT\f[], the transaction is aborted. .PP The \f[B]TX_FREE\f[]() macro transactionally frees the memory space represented by an object handle \f[I]o\f[]. If \f[I]o\f[] is \f[B]OID_NULL\f[], no operation is performed. If successful and called during \f[B]TX_STAGE_WORK\f[], \f[B]TX_FREE\f[]() returns 0. Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[] and \f[I]errno\f[] is set appropriately. .PP The \f[B]TX_XFREE\f[]() macro transactionally frees the memory space represented by an object handle \f[I]o\f[]. If \f[I]o\f[] is \f[B]OID_NULL\f[], no operation is performed. The \f[I]flags\f[] argument is a bitmask of values described in \f[B]pmemobj_tx_xfree\f[] section. If successful and called during \f[B]TX_STAGE_WORK\f[], \f[B]TX_FREE\f[]() returns 0. Otherwise, the error number is returned, \f[B]errno\f[] is set and when flags do not contain \f[B]POBJ_XFREE_NO_ABORT\f[], the transaction is aborted. .SH RETURN VALUE .PP On success, the \f[B]pmemobj_tx_alloc\f[](), \f[B]pmemobj_tx_zalloc\f[](), \f[B]pmemobj_tx_strdup\f[]() and \f[B]pmemobj_tx_wcsdup\f[]() functions return a handle to the newly allocated object. Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[], \f[B]OID_NULL\f[] is returned, and \f[I]errno\f[] is set appropriately. If \f[I]size\f[] equals 0, \f[B]OID_NULL\f[] is returned and \f[I]errno\f[] is set appropriately. .PP On success, the \f[B]pmemobj_tx_xalloc\f[](), \f[B]pmemobj_tx_xstrdup\f[]() and \f[B]pmemobj_tx_xwcsdup\f[]() functions return a handle to the newly allocated object. Otherwise, the \f[B]OID_NULL\f[] is returned, \f[B]errno\f[] is set and when flags do not contain \f[B]POBJ_XALLOC_NO_ABORT\f[], the transaction is aborted. .PP On success, \f[B]pmemobj_tx_realloc\f[]() and \f[B]pmemobj_tx_zrealloc\f[]() return a handle to the resized object. Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[], \f[B]OID_NULL\f[] is returned, and \f[I]errno\f[] 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[]() returns 0. Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[], \f[B]errno\f[] is set appropriately and transaction is aborted .PP On success \f[B]pmemobj_tx_xfree\f[]() returns 0. Otherwise, the error number is returned, \f[B]errno\f[] is set and when flags do not contain \f[B]POBJ_XFREE_NO_ABORT\f[], the transaction is aborted. .SH SEE ALSO .PP \f[B]pmemobj_tx_add_range\f[](3), \f[B]pmemobj_tx_begin\f[](3), \f[B]libpmemobj\f[](7) and \f[B]\f[]