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>