pmemobj API version 2.3

The PMDK repository on GitHub is the ultimate source of information on PMDK from release 2.0! For all questions and to submit eventual issues please follow to that repository. The PMDK documentation collected here should be valid up to the 1.13.1 release but is maintained only on a best-effort basis and may not reflect the latest state of the art.

NAME
SYNOPSIS
DESCRIPTION
RETURN VALUE
SEE ALSO

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_id

  • POBJ_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

The contents of this web site and the associated GitHub repositories are BSD-licensed open source.