1PMEMOBJ_ACTION(3) PMDK Programmer's Manual PMEMOBJ_ACTION(3)
2
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
11 #include <libpmemobj.h>
12 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 POBJ_RESERVE_NEW(pop, t, act)
24 POBJ_RESERVE_ALLOC(pop, t, size, act)
25
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 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 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 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 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 pmemobj_xreserve() is equivalent to pmemobj_reserve(), but with an ad‐
60 ditional flags argument that is a bitmask of the following values:
61 · POBJ_XALLOC_ZERO - zero the object
63 · POBJ_CLASS_ID(class_id) - allocate the object from allocation class
65 class_id. The class id cannot be 0.
66 The pmemobj_set_value function prepares an action that, once published,
68 will modify the memory location pointed to by ptr to value.
69 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 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 The pmemobj_cancel function releases any resources held by the provided
82 set of actions and invalidates all actions.
83 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 The POBJ_RESERVE_ALLOC macro is a typed variant of pmemobj_reserve.
88 The size of the reservation is user-provided.
89
91 The following code shows atomic append of two objects into a singly
92 linked list.
93 struct list_node {
95 int value;
96 PMEMoid next;
97 };
98 /* statically allocate the array of actions */
99 struct pobj_action actv[4];
100 /* 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 /* 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 /* 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 /* atomically publish the above actions */
122 pmemobj_publish(pop, actv, 4);
123
125 On success, pmemobj_reserve() functions return a handle to the newly
126 reserved object, otherwise an OID_NULL is returned.
127 On success, pmemobj_tx_publish() returns 0, otherwise, stage changes to
129 TX_STAGE_ONABORT and errno is set appropriately
130
132 pmemobj_alloc(3), pmemobj_tx_alloc(3), libpmemobj(7) and
133 <http://pmem.io>
134PMDK - pmemobj API version 2.3 2018-03-13 PMEMOBJ_ACTION(3)