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

NAME

6       pmemobj_reserve(),   pmemobj_xreserve(),  pmemobj_defer_free(),  pmemo‐
7       bj_set_value(), pmemobj_publish(),  pmemobj_tx_publish(),  pmemobj_can‐
8       cel(),      POBJ_RESERVE_NEW(),     POBJ_RESERVE_ALLOC(),     POBJ_XRE‐
9       SERVE_NEW(),POBJ_XRESERVE_ALLOC() - Delayed atomicity actions  (EXPERI‐
10       MENTAL)
11

SYNOPSIS

13              #include <libpmemobj.h>
14
15              PMEMoid pmemobj_reserve(PMEMobjpool *pop, struct pobj_action *act,
16                  size_t size, uint64_t type_num); (EXPERIMENTAL)
17              PMEMoid pmemobj_xreserve(PMEMobjpool *pop, struct pobj_action *act,
18                  size_t size, uint64_t type_num, uint64_t flags); (EXPERIMENTAL)
19              void pmemobj_defer_free(PMEMobjpool *pop, PMEMoid oid, struct pobj_action *act);
20              void pmemobj_set_value(PMEMobjpool *pop, struct pobj_action *act,
21                  uint64_t *ptr, uint64_t value); (EXPERIMENTAL)
22              int pmemobj_publish(PMEMobjpool *pop, struct pobj_action *actv,
23                  size_t actvcnt); (EXPERIMENTAL)
24              int pmemobj_tx_publish(struct pobj_action *actv, size_t actvcnt); (EXPERIMENTAL)
25              pmemobj_cancel(PMEMobjpool *pop, struct pobj_action *actv,
26                  size_t actvcnt); (EXPERIMENTAL)
27
28              POBJ_RESERVE_NEW(pop, t, act) (EXPERIMENTAL)
29              POBJ_RESERVE_ALLOC(pop, t, size, act) (EXPERIMENTAL)
30              POBJ_XRESERVE_NEW(pop, t, act, flags) (EXPERIMENTAL)
31              POBJ_XRESERVE_ALLOC(pop, t, size, act, flags) (EXPERIMENTAL)
32

DESCRIPTION

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

EXAMPLES

105       The  following  code  shows  atomic append of two objects into a singly
106       linked list.
107
108              struct list_node {
109                  int value;
110                  PMEMoid next;
111              };
112              /* statically allocate the array of actions */
113              struct pobj_action actv[4];
114
115              /* reserve, populate and persist the first object */
116              PMEMoid tail = pmemobj_reserve(pop, &actv[0], sizeof(struct list_node), 0);
117              if (TOID_IS_NULL(tail))
118                  return -1;
119              D_RW(tail)->value = 1;
120              D_RW(tail)->next = OID_NULL;
121              pmemobj_persist(pop, D_RW(tail), sizeof(struct list_node));
122
123              /* reserve, populate and persist the second object */
124              PMEMoid head = pmemobj_reserve(pop, &actv[1], sizeof(struct list_node), 0);
125              if (TOID_IS_NULL(head))
126                  return -1;
127              D_RW(head)->value = 2;
128              D_RW(head)->next = tail;
129              pmemobj_persist(pop, D_RW(head), sizeof(struct list_node));
130
131              /* create actions to set the PMEMoid to the new values */
132              pmemobj_set_value(pop, &actv[2], &D_RO(root)->head.pool_uuid_lo, head.pool_uuid_lo);
133              pmemobj_set_value(pop, &actv[3], &D_RO(root)->head.off, head.off);
134
135              /* atomically publish the above actions */
136              pmemobj_publish(pop, actv, 4);
137

RETURN VALUE

139       On success, pmemobj_reserve() functions return a handle  to  the  newly
140       reserved object, otherwise an OID_NULL is returned.
141
142       On success, pmemobj_tx_publish() returns 0, otherwise, stage changes to
143       TX_STAGE_ONABORT and errno is set appropriately
144
145       On success, pmemobj_publish() returns 0, otherwise, returns -1 and  er‐
146       rno is set appropriately.
147

SEE ALSO

149       pmemobj_alloc(3),      pmemobj_tx_alloc(3),      libpmemobj(7)      and
150       <http://pmem.io>
151
152
153
154PMDK - pmemobj API version 2.3    2018-10-01                 PMEMOBJ_ACTION(3)
Impressum