.\" Automatically generated by Pandoc 2.10.1
.\"
.TH "PMEMOBJ_ACTION" "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_reserve\f[R](), \f[B]pmemobj_xreserve\f[R](),
\f[B]pmemobj_defer_free\f[R](), \f[B]pmemobj_set_value\f[R](),
\f[B]pmemobj_publish\f[R](), \f[B]pmemobj_tx_publish\f[R](),
\f[B]pmemobj_tx_xpublish\f[R](), \f[B]pmemobj_cancel\f[R](),
\f[B]POBJ_RESERVE_NEW\f[R](), \f[B]POBJ_RESERVE_ALLOC\f[R](),
\f[B]POBJ_XRESERVE_NEW\f[R](),\f[B]POBJ_XRESERVE_ALLOC\f[R]() - Delayed
atomicity actions (EXPERIMENTAL)
.SH SYNOPSIS
.IP
.nf
\f[C]
#include <libpmemobj.h>

PMEMoid pmemobj_reserve(PMEMobjpool *pop, struct pobj_action *act,
    size_t size, uint64_t type_num); (EXPERIMENTAL)
PMEMoid pmemobj_xreserve(PMEMobjpool *pop, struct pobj_action *act,
    size_t size, uint64_t type_num, uint64_t flags); (EXPERIMENTAL)
void pmemobj_defer_free(PMEMobjpool *pop, PMEMoid oid, struct pobj_action *act);
void pmemobj_set_value(PMEMobjpool *pop, struct pobj_action *act,
    uint64_t *ptr, uint64_t value); (EXPERIMENTAL)
int pmemobj_publish(PMEMobjpool *pop, struct pobj_action *actv,
    size_t actvcnt); (EXPERIMENTAL)
int pmemobj_tx_publish(struct pobj_action *actv, size_t actvcnt); (EXPERIMENTAL)
int pmemobj_tx_xpublish(struct pobj_action *actv, size_t actvcnt, uint64_t flags); (EXPERIMENTAL)
void pmemobj_cancel(PMEMobjpool *pop, struct pobj_action *actv,
    size_t actvcnt); (EXPERIMENTAL)

POBJ_RESERVE_NEW(pop, t, act) (EXPERIMENTAL)
POBJ_RESERVE_ALLOC(pop, t, size, act) (EXPERIMENTAL)
POBJ_XRESERVE_NEW(pop, t, act, flags) (EXPERIMENTAL)
POBJ_XRESERVE_ALLOC(pop, t, size, act, flags) (EXPERIMENTAL)
\f[R]
.fi
.SH DESCRIPTION
.PP
All of the functions described so far have an immediate effect on the
persistent state of the pool, and as such, the cost of maintaining
fail-safety is paid outright and, most importantly, in the calling
thread.
This behavior makes implementing algorithms involving relaxed
consistency guarantees difficult, if not outright impossible.
.PP
The following set of functions introduce a mechanism that allows one to
delay the persistent publication of a set of prepared actions to an
arbitrary moment in time of the execution of a program.
.PP
The publication is fail-safe atomic in the scope of the entire
collection of actions.
If a program exits without publishing the actions, or the actions are
canceled, any resources reserved by those actions are released and
placed back in the pool.
.PP
A single action is represented by a single \f[C]struct pobj_action\f[R].
Functions that create actions take that structure by pointer, whereas
functions that publish actions take array of actions and the size of the
array.
The actions can be created, and published, from different threads.
When creating actions, the \f[I]act\f[R] argument must be non-NULL and
point to a \f[C]struct pobj_action\f[R], the structure will be populated
by the function and must not be modified or deallocated until after
publishing.
.PP
The \f[B]pmemobj_reserve\f[R]() functions performs a transient
reservation of an object.
Behaves similarly to \f[B]pmemobj_alloc\f[R](3), but performs no
modification to the persistent state.
The object returned by this function can be freely modified without
worrying about fail-safe atomicity until the object has been published.
Any modifications of the object must be manually persisted, just like in
the case of the atomic API.
.PP
\f[B]pmemobj_xreserve\f[R]() is equivalent to
\f[B]pmemobj_reserve\f[R](), but with an additional \f[I]flags\f[R]
argument that is a bitmask of the following values:
.IP \[bu] 2
\f[B]POBJ_XALLOC_ZERO\f[R] - zero the allocated object (and persist it)
.IP \[bu] 2
\f[B]POBJ_CLASS_ID(class_id)\f[R] - allocate an object from the
allocation class \f[I]class_id\f[R].
The class id cannot be 0.
.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.
.PP
\f[B]pmemobj_defer_free\f[R]() function creates a deferred free action,
meaning that the provided object will be freed when the action is
published.
Calling this function with a NULL OID is invalid and causes undefined
behavior.
.PP
The \f[B]pmemobj_set_value\f[R] function prepares an action that, once
published, will modify the memory location pointed to by \f[I]ptr\f[R]
to \f[I]value\f[R].
.PP
The \f[B]pmemobj_publish\f[R] function publishes the provided set of
actions.
The publication is fail-safe atomic.
Once done, the persistent state will reflect the changes contained in
the actions.
.PP
The \f[B]pmemobj_tx_publish\f[R] function moves the provided actions to
the scope of the transaction in which it is called.
Only object reservations are supported in transactional publish.
Once done, the reserved objects will follow normal transactional
semantics.
Can only be called during \f[I]TX_STAGE_WORK\f[R].
.PP
The \f[B]pmemobj_tx_xpublish\f[R]() function behaves exactly the same as
\f[B]pmemobj_tx_publish\f[R]() when \f[I]flags\f[R] equals zero.
\f[I]flags\f[R] is a bitmask of the following values:
.IP \[bu] 2
\f[B]POBJ_XPUBLISH_NO_ABORT\f[R] - if the function does not end
successfully, do not abort the transaction.
.PP
The \f[B]pmemobj_cancel\f[R] function releases any resources held by the
provided set of actions and invalidates all actions.
.PP
The \f[B]POBJ_RESERVE_NEW\f[R] macro is a typed variant of
\f[B]pmemobj_reserve\f[R].
The size of the reservation is determined from the provided type
\f[I]t\f[R].
.PP
The \f[B]POBJ_RESERVE_ALLOC\f[R] macro is a typed variant of
\f[B]pmemobj_reserve\f[R].
The \f[I]size\f[R] of the reservation is user-provided.
.PP
The \f[B]POBJ_XRESERVE_NEW\f[R] and the \f[B]POBJ_XRESERVE_ALLOC\f[R]
macros are equivalent to \f[B]POBJ_RESERVE_NEW\f[R] and the
\f[B]POBJ_RESERVE_ALLOC\f[R], but with an additional \f[I]flags\f[R]
argument defined for \f[B]pmemobj_xreserve\f[R]().
.SH EXAMPLES
.PP
The following code shows atomic append of two objects into a singly
linked list.
.IP
.nf
\f[C]
struct list_node {
    int value;
    PMEMoid next;
};
/* statically allocate the array of actions */
struct pobj_action actv[4];

/* reserve, populate and persist the first object */
PMEMoid tail = pmemobj_reserve(pop, &actv[0], sizeof(struct list_node), 0);
if (TOID_IS_NULL(tail))
    return -1;
D_RW(tail)->value = 1;
D_RW(tail)->next = OID_NULL;
pmemobj_persist(pop, D_RW(tail), sizeof(struct list_node));

/* reserve, populate and persist the second object */
PMEMoid head = pmemobj_reserve(pop, &actv[1], sizeof(struct list_node), 0);
if (TOID_IS_NULL(head))
    return -1;
D_RW(head)->value = 2;
D_RW(head)->next = tail;
pmemobj_persist(pop, D_RW(head), sizeof(struct list_node));

/* create actions to set the PMEMoid to the new values */
pmemobj_set_value(pop, &actv[2], &D_RO(root)->head.pool_uuid_lo, head.pool_uuid_lo);
pmemobj_set_value(pop, &actv[3], &D_RO(root)->head.off, head.off);

/* atomically publish the above actions */
pmemobj_publish(pop, actv, 4);
\f[R]
.fi
.SH RETURN VALUE
.PP
On success, \f[B]pmemobj_reserve\f[R]() functions return a handle to the
newly reserved object.
Otherwise an \f[I]OID_NULL\f[R] is returned.
.PP
On success, \f[B]pmemobj_tx_publish\f[R]() returns 0.
Otherwise, the transaction is aborted, the stage is changed to
\f[I]TX_STAGE_ONABORT\f[R] and \f[I]errno\f[R] is set appropriately.
.PP
On success, \f[B]pmemobj_tx_xpublish\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_XPUBLISH_NO_ABORT\f[R], the transaction
is aborted.
.PP
On success, \f[B]pmemobj_publish\f[R]() returns 0.
Otherwise, returns -1 and \f[I]errno\f[R] is set appropriately.
.SH SEE ALSO
.PP
\f[B]pmemobj_alloc\f[R](3), \f[B]pmemobj_tx_alloc\f[R](3),
\f[B]libpmemobj\f[R](7) and \f[B]<https://pmem.io>\f[R]