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.

comment: <> (SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT) comment: <> (LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,) comment: <> (DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY) comment: <> (THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT) comment: <> ((INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE) comment: <> (OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.)

NAME
SYNOPSIS
DESCRIPTION
RETURN VALUE
EXAMPLES
SEE ALSO

NAME

pmemobj_reserve(), pmemobj_xreserve(), pmemobj_set_value(), pmemobj_publish(), pmemobj_tx_publish(), pmemobj_cancel(), POBJ_RESERVE_NEW(), POBJ_RESERVE_ALLOC()

  • Delayed atomicity actions (EXPERIMENTAL)

SYNOPSIS

#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_set_value(PMEMobjpool *pop, struct pobj_action *act,
	uint64_t *ptr, uint64_t value); (EXPERIMENTAL)
void pmemobj_publish(PMEMobjpool *pop, struct pobj_action *actv,
	size_t actvcnt); (EXPERIMENTAL)
int pmemobj_tx_publish(struct pobj_action *actv, size_t actvcnt); (EXPERIMENTAL)
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)

DESCRIPTION

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.

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.

The publication is fail-safe atomic in the scope of the entire collection of actions, but the number of said actions is limited by POBJ_MAX_ACTIONS constant. If a program exists without publishing the actions, or the actions are canceled, any resources reserved by those actions are released and placed back in the pool.

A single action is represented by a single struct pobj_action. 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 act argument must be non-NULL and point to a struct pobj_action, the structure will be populated by the function and must not be modified or deallocated until after publishing.

The pmemobj_reserve() functions performs a transient reservation of an object. Behaves similarly to pmemobj_alloc(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.

pmemobj_xreserve() is equivalent to pmemobj_reserve(), but with an additional flags argument that is a bitmask of the following values:

  • POBJ_XALLOC_ZERO - zero the object

  • POBJ_CLASS_ID(class_id) - allocate the object from allocation class class_id. The class id cannot be 0.

The pmemobj_set_value function prepares an action that, once published, will modify the memory location pointed to by ptr to value.

The pmemobj_publish 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. The actvcnt cannot exceed POBJ_MAX_ACTIONS.

The pmemobj_tx_publish 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 TX_STAGE_WORK.

The pmemobj_cancel function releases any resources held by the provided set of actions and invalidates all actions.

The POBJ_RESERVE_NEW macro is a typed variant of pmemobj_reserve. The size of the reservation is determined from the provided type t.

The POBJ_RESERVE_ALLOC macro is a typed variant of pmemobj_reserve. The size of the reservation is user-provided.

EXAMPLES

The following code shows atomic append of two objects into a singly linked list.

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);

RETURN VALUE

On success, pmemobj_reserve() functions return a handle to the newly reserved object, otherwise an OID_NULL is returned.

On success, pmemobj_tx_publish() returns 0, otherwise, stage changes to TX_STAGE_ONABORT and errno is set appropriately

SEE ALSO

pmemobj_alloc(3), pmemobj_tx_alloc(3), libpmemobj(7) and http://pmem.io

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