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>