1PMEMOBJ_ACTION(3)          PMDK Programmer's Manual          PMEMOBJ_ACTION(3)
2
3
4

NAME

6       pmemobj_reserve(),   pmemobj_xreserve(),   pmemobj_set_value(),  pmemo‐
7       bj_publish(),    pmemobj_tx_publish(),    pmemobj_cancel(),    POBJ_RE‐
8       SERVE_NEW(), POBJ_RESERVE_ALLOC() -- Delayed atomicity actions
9

SYNOPSIS

11              #include <libpmemobj.h>
12
13              PMEMoid pmemobj_reserve(PMEMobjpool *pop, struct pobj_action *act,
14                  size_t size, uint64_t type_num);
15              PMEMoid pmemobj_xreserve(PMEMobjpool *pop, struct pobj_action *act,
16                  size_t size, uint64_t type_num, uint64_t flags);
17              void pmemobj_set_value(PMEMobjpool *pop, struct pobj_action *act,
18                  uint64_t *ptr, uint64_t value);
19              void pmemobj_publish(PMEMobjpool *pop, struct pobj_action *actv, size_t actvcnt);
20              int pmemobj_tx_publish(struct pobj_action *actv, size_t actvcnt);
21              pmemobj_cancel(PMEMobjpool *pop, struct pobj_action *actv, size_t actvcnt);
22
23              POBJ_RESERVE_NEW(pop, t, act)
24              POBJ_RESERVE_ALLOC(pop, t, size, act)
25

DESCRIPTION

27       All  of  the functions described so far have an immediate effect on the
28       persistent state of the pool, and as  such,  the  cost  of  maintaining
29       fail-safety  is  paid  outright  and,  most importantly, in the calling
30       thread.  This behavior makes implementing algorithms involving  relaxed
31       consistency guarantees difficult, if not outright impossible.
32
33       The following set of functions introduce a mechanism that allows one to
34       delay the persistent publication of a set of prepared actions to an ar‐
35       bitrary moment in time of the execution of a program.
36
37       The  publication is fail-safe atomic in the scope of the entire collec‐
38       tion of  actions,  but  the  number  of  said  actions  is  limited  by
39       POBJ_MAX_ACTIONS  constant.  If a program exists without publishing the
40       actions, or the actions are canceled, any resources reserved  by  those
41       actions are released and placed back in the pool.
42
43       A  single  action is represented by a single struct pobj_action.  Func‐
44       tions that create actions take that structure by pointer, whereas func‐
45       tions  that  publish  actions take array of actions and the size of the
46       array.  The actions can  be  created,  and  published,  from  different
47       threads.   When creating actions, the act argument must be non-NULL and
48       point to a struct pobj_action, the structure will be populated  by  the
49       function  and  must not be modified or deallocated until after publish‐
50       ing.
51
52       The pmemobj_reserve() functions performs a transient reservation of  an
53       object.  Behaves similarly to pmemobj_alloc(3), but performs no modifi‐
54       cation to the persistent state.  The object returned by  this  function
55       can be freely modified without worrying about fail-safe atomicity until
56       the object has been published.  Any modifications of the object must be
57       manually persisted, just like in the case of the atomic API.
58
59       pmemobj_xreserve()  is equivalent to pmemobj_reserve(), but with an ad‐
60       ditional flags argument that is a bitmask of the following values:
61
62       · POBJ_XALLOC_ZERO - zero the object
63
64       · POBJ_CLASS_ID(class_id) - allocate the object from  allocation  class
65         class_id.  The class id cannot be 0.
66
67       The pmemobj_set_value function prepares an action that, once published,
68       will modify the memory location pointed to by ptr to value.
69
70       The pmemobj_publish function publishes the  provided  set  of  actions.
71       The  publication  is fail-safe atomic.  Once done, the persistent state
72       will reflect the changes contained in the actions.  The actvcnt  cannot
73       exceed POBJ_MAX_ACTIONS.
74
75       The pmemobj_tx_publish function moves the provided actions to the scope
76       of the transaction in which it is called.  Only object reservations are
77       supported  in  transactional  publish.  Once done, the reserved objects
78       will follow normal transactional semantics.  Can only be called  during
79       TX_STAGE_WORK.
80
81       The pmemobj_cancel function releases any resources held by the provided
82       set of actions and invalidates all actions.
83
84       The POBJ_RESERVE_NEW macro is a typed variant of pmemobj_reserve.   The
85       size of the reservation is determined from the provided type t.
86
87       The  POBJ_RESERVE_ALLOC  macro  is  a typed variant of pmemobj_reserve.
88       The size of the reservation is user-provided.
89

EXAMPLES

91       The following code shows atomic append of two  objects  into  a  singly
92       linked list.
93
94              struct list_node {
95                  int value;
96                  PMEMoid next;
97              };
98              /* statically allocate the array of actions */
99              struct pobj_action actv[4];
100
101              /* reserve, populate and persist the first object */
102              PMEMoid tail = pmemobj_reserve(pop, &actv[0], sizeof(struct list_node), 0);
103              if (TOID_IS_NULL(tail))
104                  return -1;
105              D_RW(tail)->value = 1;
106              D_RW(tail)->next = OID_NULL;
107              pmemobj_persist(pop, D_RW(tail), sizeof(struct list_node));
108
109              /* reserve, populate and persist the second object */
110              PMEMoid head = pmemobj_reserve(pop, &actv[1], sizeof(struct list_node), 0);
111              if (TOID_IS_NULL(head))
112                  return -1;
113              D_RW(head)->value = 2;
114              D_RW(head)->next = tail;
115              pmemobj_persist(pop, D_RW(head), sizeof(struct list_node));
116
117              /* create actions to set the PMEMoid to the new values */
118              pmemobj_set_value(pop, &actv[2], &D_RO(root)->head.pool_uuid_lo, head.pool_uuid_lo);
119              pmemobj_set_value(pop, &actv[3], &D_RO(root)->head.off, head.off);
120
121              /* atomically publish the above actions */
122              pmemobj_publish(pop, actv, 4);
123

RETURN VALUE

125       On  success,  pmemobj_reserve()  functions return a handle to the newly
126       reserved object, otherwise an OID_NULL is returned.
127
128       On success, pmemobj_tx_publish() returns 0, otherwise, stage changes to
129       TX_STAGE_ONABORT and errno is set appropriately
130

SEE ALSO

132       pmemobj_alloc(3),      pmemobj_tx_alloc(3),      libpmemobj(7)      and
133       <http://pmem.io>
134
135
136
137PMDK - pmemobj API version 2.3    2018-03-13                 PMEMOBJ_ACTION(3)
Impressum