Man page - tx_new(3)

Packages contains this manual

Package:  libpmemobj-dev
apt-get install libpmemobj-dev

Manuals in package:
• pmemobj_tx_realloc(3)
• pobj_first(3)
• pmemobj_f_mem_wc(3)
• pmemobj_tx_xwcsdup(3)
• toid_equals(3)
• pmemobj_f_mem_nodrain(3)
• pmemobj_next(3)
• pmemobj_tx_stage(3)
• pmemobj_tx_strdup(3)
• pobj_list_move_element_tail(3)
• pmemobj_tx_begin(3)
• pmemobj_rwlock_tryrdlock(3)
• tx_xadd_direct(3)
• pobj_layout_end(3)
• pobj_znew(3)
• pmemobj_tx_xstrdup(3)
• pmemobj_f_relaxed(3)
• pmemobj_set_user_data(3)
• pobj_reserve_alloc(3)
• tx_xalloc(3)
• pmemobj_tx_log_intents_max_size(3)
• pmemobj_tx_get_failure_behavior(3)
• tx_xstrdup(3)
• pmemobj_action(3)
• tx_add_field(3)
• pmemobj_tx_wcsdup(3)
• pmemobj_memmove(3)
• toid_valid(3)
• pmemobj_tx_free(3)
• pobj_list_insert_tail(3)
• pmemobj_list_insert_new(3)
• tx_add_field_direct(3)
• pobj_layout_types_num(3)
• pmemobj_ctl_set(3)
• pmemobj_close(3)
• pmemobj_root(3)
• pmemobj_mutex_trylock(3)
• toid_assign(3)
• pmemobj_open(3)
• pmemobj_root_construct(3)
• pobj_layout_begin(3)
• pobj_list_first(3)
• pmemobj_pool_by_oid(3)
• pobj_layout_root(3)
• pmemobj_tx_lock(3)
• pmemobj_pool_by_ptr(3)
• pmemobj_realloc(3)
• tx_xadd_field_direct(3)
• pmemobj_create(3)
• pobj_free(3)
• pmemobj_free(3)
• pobj_xreserve_new(3)
• pmemobj_rwlock_trywrlock(3)
• pmemobj_errormsg(3)
• pmemobj_zalloc(3)
• pobj_foreach_safe_type(3)
• direct_rw(3)
• pmemobj_persist(3)
• pmemobj_get_user_data(3)
• libpmemobj(7)
• tx_realloc(3)
• pobj_list_move_element_before(3)
• pmemobj_cond_timedwait(3)
• pmemobj_tx_xalloc(3)
• pmemobj_rwlock_timedwrlock(3)
• tx_memset(3)
• pobj_list_prev(3)
• pmemobj_tx_abort(3)
• tx_xadd(3)
• pmemobj_tx_set_failure_behavior(3)
• pobj_zrealloc(3)
• tx_begin_param(3)
• direct_ro(3)
• oid_instanceof(3)
• pmemobj_tx_errno(3)
• pobj_next_type_num(3)
• pmemobj_direct(3)
• pobj_foreach_safe(3)
• pmemobj_cond_broadcast(3)
• pmemobj_tx_log_snapshots_max_size(3)
• pobj_zalloc(3)
• pobj_root(3)
• pobj_list_foreach_reverse(3)
• pobj_new(3)
• pmemobj_drain(3)
• d_ro(3)
• pmemobj_zrealloc(3)
• pobj_list_insert_after(3)
• pmemobj_check_version(3)
• pmemobj_set_funcs(3)
• pmemobj_tx_log_append_buffer(3)
• pmemobj_publish(3)
• pobj_list_insert_before(3)
• pmemobj_f_mem_noflush(3)
• tx_onabort(3)
• pobj_list_empty(3)
• pmemobj_mutex_unlock(3)
• pmemobj_cond_zero(3)
• pmemobj_tx_xadd_range(3)
• pmemobj_tx_get_user_data(3)
• tx_zrealloc(3)
• pmemobj_tx_zrealloc(3)
• pmemobj_xflush(3)
• toid_typeof(3)
• pmemobj_f_mem_nontemporal(3)
• tx_wcsdup(3)
• pobj_layout_name(3)
• pmemobj_list_move(3)
• pmemobj_tx_xlock(3)
• oid_is_null(3)
• pmemobj_tx_publish(3)
• toid_declare_root(3)
• pobj_list_entry(3)
• pobj_list_insert_new_after(3)
• pmemobj_tx_end(3)
• pobj_list_move_element_head(3)
• pmemobj_list_insert(3)
• pmemobj_tx_commit(3)
• pmemobj_cond_wait(3)
• toid_declare(3)
• pmemobj_set_value(3)
• pmemobj_xalloc(3)
• tx_zalloc(3)
• d_rw(3)
• tx_strdup(3)
• pmemobj_cancel(3)
• pobj_list_foreach(3)
• pmemobj_rwlock_unlock(3)
• pmemobj_memcpy(3)
• pobj_first_type_num(3)
• pmemobj_tx_process(3)
• tx_begin(3)
• toid_is_null(3)
• tx_free(3)
• toid_type_num_of(3)
• pmemobj_mutex_zero(3)
• pobj_foreach_type(3)
• pmemobj_rwlock_wrlock(3)
• pmemobj_tx_xfree(3)
• pmemobj_mutex_lock(3)
• pmemobj_oid(3)
• pmemobj_tx_xadd_range_direct(3)
• pobj_list_head(3)
• pmemobj_memset(3)
• pmemobj_root_size(3)
• tx_xwcsdup(3)
• pobj_list_insert_head(3)
• pmemobj_wcsdup(3)
• pobj_list_last(3)
• pmemobj_type_num(3)
• tx_set(3)
• pmemobj_defrag(3)
• pmemobj_volatile(3)
• pobj_list_next(3)
• pobj_xreserve_alloc(3)
• pmemobj_rwlock_rdlock(3)
• pmemobj_check(3)
• pmemobj_memcpy_persist(3)
• pobj_list_insert_new_before(3)
• tx_set_direct(3)
• pobj_list_remove(3)
• pobj_list_remove_free(3)
• pmemobj_tx_set_user_data(3)
• pmemobj_mutex_timedlock(3)
• pobj_foreach(3)
• pmemobj_tx_zalloc(3)
• pmemobj_reserve(3)
• toid(3)
• pmemobj_defer_free(3)
• pmemobj_flush(3)
• tx_add_direct(3)
• pmemobj_alloc_usable_size(3)
• pmemobj_tx_log_auto_alloc(3)
• pmemobj_first(3)
• toid_type_num(3)
• pmemobj_ctl_exec(3)
• pmemobj_alloc(3)
• pmemobj_tx_add_range_direct(3)
• tx_oncommit(3)
• tx_alloc(3)
• pmemobj_tx_add_range(3)
• tx_xadd_field(3)
• pobj_realloc(3)
• tx_finally(3)
• pobj_next(3)
• toid_offsetof(3)
• tx_memcpy(3)
• pmemobj_xpersist(3)
• tx_add(3)
• pobj_list_insert_new_head(3)
• pmemobj_xreserve(3)
• pmemobj_strdup(3)
• tx_new(3)
• pobj_layout_toid(3)
• pmemobj_rwlock_zero(3)
• pmemobj_rwlock_timedrdlock(3)
• tx_begin_cb(3)
• tx_znew(3)
• pmemobj_f_mem_temporal(3)
• pmemobj_ctl_get(3)
• tx_end(3)
• pmemobj_cond_signal(3)
• pmemobj_list_remove(3)
• pobj_list_insert_new_tail(3)
• pmemobj_tx_xlog_append_buffer(3)
• pobj_reserve_new(3)
• tx_xfree(3)
• pmemobj_f_mem_wb(3)
• pobj_alloc(3)
• oid_equals(3)
• pobj_list_move_element_after(3)
• pmemobj_tx_alloc(3)
• pmemobj_memset_persist(3)
• pmemobj_tx_xpublish(3)
Documentations in package:
• libpmemobj-dev

Manual

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>

---