1() PMDK Programmer's Manual ()
2
6 POBJ_LIST_HEAD(), POBJ_LIST_ENTRY(), POBJ_LIST_FIRST(),
7 POBJ_LIST_LAST(), POBJ_LIST_EMPTY(), POBJ_LIST_NEXT(),
8 POBJ_LIST_PREV(),
9 POBJ_LIST_FOREACH(), POBJ_LIST_FOREACH_REVERSE(),
11 POBJ_LIST_INSERT_HEAD(), POBJ_LIST_INSERT_TAIL(), POBJ_LIST_INSERT_AF‐
13 TER(), POBJ_LIST_INSERT_BEFORE(), POBJ_LIST_INSERT_NEW_HEAD(),
14 POBJ_LIST_INSERT_NEW_TAIL(), POBJ_LIST_INSERT_NEW_AFTER(),
15 POBJ_LIST_INSERT_NEW_BEFORE(),
16 POBJ_LIST_REMOVE(), POBJ_LIST_REMOVE_FREE(),
18 POBJ_LIST_MOVE_ELEMENT_HEAD(), POBJ_LIST_MOVE_ELEMENT_TAIL(),
20 POBJ_LIST_MOVE_ELEMENT_AFTER(), POBJ_LIST_MOVE_ELEMENT_BEFORE() - type-
21 safe non-transactional persistent atomic lists
22
24 #include <libpmemobj.h>
25 POBJ_LIST_HEAD(HEADNAME, TYPE)
27 POBJ_LIST_ENTRY(TYPE)
28 POBJ_LIST_FIRST(POBJ_LIST_HEAD *head)
29 POBJ_LIST_LAST(POBJ_LIST_HEAD *head, POBJ_LIST_ENTRY FIELD)
30 POBJ_LIST_EMPTY(POBJ_LIST_HEAD *head)
31 POBJ_LIST_NEXT(TOID elm, POBJ_LIST_ENTRY FIELD)
32 POBJ_LIST_PREV(TOID elm, POBJ_LIST_ENTRY FIELD)
33 POBJ_LIST_FOREACH(TOID var, POBJ_LIST_HEAD *head, POBJ_LIST_ENTRY FIELD)
35 POBJ_LIST_FOREACH_REVERSE(TOID var, POBJ_LIST_HEAD *head, POBJ_LIST_ENTRY FIELD)
36 POBJ_LIST_INSERT_HEAD(PMEMobjpool *pop, POBJ_LIST_HEAD *head,
38 TOID elm, POBJ_LIST_ENTRY FIELD)
39 POBJ_LIST_INSERT_TAIL(PMEMobjpool *pop, POBJ_LIST_HEAD *head,
40 TOID elm, POBJ_LIST_ENTRY FIELD)
41 POBJ_LIST_INSERT_AFTER(PMEMobjpool *pop, POBJ_LIST_HEAD *head,
42 TOID listelm, TOID elm, POBJ_LIST_ENTRY FIELD)
43 POBJ_LIST_INSERT_BEFORE(PMEMobjpool *pop, POBJ_LIST_HEAD *head,
44 TOID listelm, TOID elm, POBJ_LIST_ENTRY FIELD)
45 POBJ_LIST_INSERT_NEW_HEAD(PMEMobjpool *pop, POBJ_LIST_HEAD *head,
46 POBJ_LIST_ENTRY FIELD, size_t size,
47 pmemobj_constr constructor, void *arg)
48 POBJ_LIST_INSERT_NEW_TAIL(PMEMobjpool *pop, POBJ_LIST_HEAD *head,
49 POBJ_LIST_ENTRY FIELD, size_t size,
50 pmemobj_constr constructor, void *arg)
51 POBJ_LIST_INSERT_NEW_AFTER(PMEMobjpool *pop, POBJ_LIST_HEAD *head,
52 TOID listelm, POBJ_LIST_ENTRY FIELD, size_t size,
53 pmemobj_constr constructor, void *arg)
54 POBJ_LIST_INSERT_NEW_BEFORE(PMEMobjpool *pop, POBJ_LIST_HEAD *head,
55 TOID listelm, POBJ_LIST_ENTRY FIELD, size_t size,
56 pmemobj_constr constructor, void *arg)
57 POBJ_LIST_REMOVE(PMEMobjpool *pop, POBJ_LIST_HEAD *head,
59 TOID elm, POBJ_LIST_ENTRY FIELD)
60 POBJ_LIST_REMOVE_FREE(PMEMobjpool *pop, POBJ_LIST_HEAD *head,
61 TOID elm, POBJ_LIST_ENTRY FIELD)
62 POBJ_LIST_MOVE_ELEMENT_HEAD(PMEMobjpool *pop, POBJ_LIST_HEAD *head,
64 POBJ_LIST_HEAD *head_new, TOID elm, POBJ_LIST_ENTRY FIELD,
65 POBJ_LIST_ENTRY field_new)
66 POBJ_LIST_MOVE_ELEMENT_TAIL(PMEMobjpool *pop, POBJ_LIST_HEAD *head,
67 POBJ_LIST_HEAD *head_new, TOID elm, POBJ_LIST_ENTRY FIELD,
68 POBJ_LIST_ENTRY field_new)
69 POBJ_LIST_MOVE_ELEMENT_AFTER(PMEMobjpool *pop, POBJ_LIST_HEAD *head,
70 POBJ_LIST_HEAD *head_new, TOID listelm, TOID elm,
71 POBJ_LIST_ENTRY FIELD, POBJ_LIST_ENTRY field_new)
72 POBJ_LIST_MOVE_ELEMENT_BEFORE(PMEMobjpool *pop, POBJ_LIST_HEAD *head,
73 POBJ_LIST_HEAD *head_new, TOID listelm, TOID elm,
74 POBJ_LIST_ENTRY FIELD, POBJ_LIST_ENTRY field_new)
75
77 The following macros define and operate on a type-safe persistent atom‐
78 ic circular doubly linked list data structure that consist of a set of
79 persistent objects of a well-known type. Unlike the functions de‐
80 scribed in the previous section, these macros provide type enforcement
81 by requiring declaration of type of the objects stored in given list,
82 and not allowing mixing objects of different types in a single list.
83 The functionality and semantics of those macros is similar to circular
85 queues defined in queue(3).
86 The majority of the macros must specify the handle to the memory pool
88 pop and the name of the field in the user-defined structure, which must
89 be of type POBJ_LIST_ENTRY and is used to connect the elements in the
90 list.
91 A list is headed by a structure defined by the POBJ_LIST_HEAD() macro.
93 This structure contains an object handle of the first element on the
94 list. The elements are doubly linked so that an arbitrary element can
95 be removed without a need to traverse the list. New elements can be
96 added to the list before or after an existing element, at the head of
97 the list, or at the end of the list. A list may be traversed in either
98 direction. A POBJ_LIST_HEAD structure is declared as follows:
99 #define POBJ_LIST_HEAD(HEADNAME, TYPE)
101 struct HEADNAME
102 {
103 TOID(TYPE) pe_first;
104 PMEMmutex lock;
105 };
106 In the macro definitions, TYPE is the name of a user-defined structure,
108 that must contain a field of type POBJ_LIST_ENTRY. The argument HEAD‐
109 NAME is the name of a user-defined structure that must be declared us‐
110 ing the macro POBJ_LIST_HEAD. See the examples below for further ex‐
111 planation of how these macros are used.
112 The macro POBJ_LIST_ENTRY declares a structure that connects the ele‐
114 ments in the list.
115 #define POBJ_LIST_ENTRY(TYPE)
117 struct
118 {
119 TOID(TYPE) pe_next;
120 TOID(TYPE) pe_prev;
121 };
122 The macro POBJ_LIST_FIRST() returns the first element on the list ref‐
124 erenced by head. If the list is empty OID_NULL is returned.
125 The macro POBJ_LIST_LAST() returns the last element on the list refer‐
127 enced by head. If the list is empty OID_NULL is returned.
128 The macro POBJ_LIST_EMPTY() evaluates to 1 if the list referenced by
130 head is empty. Otherwise, 0 is returned.
131 The macro POBJ_LIST_NEXT() returns the element next to the element elm.
133 The macro POBJ_LIST_PREV() returns the element preceding the element
135 elm.
136 The macro POBJ_LIST_FOREACH() traverses the list referenced by head as‐
138 signing a handle to each element in turn to var variable.
139 The macro POBJ_LIST_FOREACH_REVERSE() traverses the list referenced by
141 head in reverse order, assigning a handle to each element in turn to
142 var variable. The field argument is the name of the field of type
143 POBJ_LIST_ENTRY in the element structure.
144 The macro POBJ_LIST_INSERT_HEAD() inserts the element elm at the head
146 of the list referenced by head.
147 The macro POBJ_LIST_INSERT_TAIL() inserts the element elm at the end of
149 the list referenced by head.
150 The macro POBJ_LIST_INSERT_AFTER() inserts the element elm into the
152 list referenced by head after the element listelm. If listelm value is
153 TOID_NULL, the object is inserted at the end of the list.
154 The macro POBJ_LIST_INSERT_BEFORE() inserts the element elm into the
156 list referenced by head before the element listelm. If listelm value
157 is TOID_NULL, the object is inserted at the head of the list.
158 The macro POBJ_LIST_INSERT_NEW_HEAD() atomically allocates a new object
160 of size size and inserts it at the head of the list referenced by head.
161 The newly allocated object is also added to the internal object con‐
162 tainer associated with a type number which is retrieved from the typed
163 OID of the first element on list.
164 The macro POBJ_LIST_INSERT_NEW_TAIL() atomically allocates a new object
166 of size size and inserts it at the tail of the list referenced by head.
167 The newly allocated object is also added to the internal object con‐
168 tainer associated with a type number which is retrieved from the typed
169 OID of the first element on list.
170 The macro POBJ_LIST_INSERT_NEW_AFTER() atomically allocates a new ob‐
172 ject of size size and inserts it into the list referenced by head after
173 the element listelm. If listelm value is TOID_NULL, the object is in‐
174 serted at the end of the list. The newly allocated object is also
175 added to the internal object container associated with with a type num‐
176 ber which is retrieved from the typed OID of the first element on list.
177 The macro POBJ_LIST_INSERT_NEW_BEFORE() atomically allocates a new ob‐
179 ject of size size and inserts it into the list referenced by head be‐
180 fore the element listelm. If listelm value is TOID_NULL, the object is
181 inserted at the head of the list. The newly allocated object is also
182 added to the internal object container associated with with a type num‐
183 ber which is retrieved from the typed OID of the first element on list.
184 The macro POBJ_LIST_REMOVE() removes the element elm from the list ref‐
186 erenced by head.
187 The macro POBJ_LIST_REMOVE_FREE() removes the element elm from the list
189 referenced by head and frees the memory space represented by this ele‐
190 ment.
191 The macro POBJ_LIST_MOVE_ELEMENT_HEAD() moves the element elm from the
193 list referenced by head to the head of the list head_new. The field
194 and field_new arguments are the names of the fields of type
195 POBJ_LIST_ENTRY in the element structure that are used to connect the
196 elements in both lists.
197 The macro POBJ_LIST_MOVE_ELEMENT_TAIL() moves the element elm from the
199 list referenced by head to the end of the list head_new. The field and
200 field_new arguments are the names of the fields of type POBJ_LIST_ENTRY
201 in the element structure that are used to connect the elements in both
202 lists.
203 The macro POBJ_LIST_MOVE_ELEMENT_AFTER() atomically removes the element
205 elm from the list referenced by head and inserts it into the list ref‐
206 erenced by head_new after the element listelm. If listelm value is
207 TOID_NULL, the object is inserted at the end of the list. The field
208 and field_new arguments are the names of the fields of type
209 POBJ_LIST_ENTRY in the element structure that are used to connect the
210 elements in both lists.
211 The macro POBJ_LIST_MOVE_ELEMENT_BEFORE() atomically removes the ele‐
213 ment elm from the list referenced by head and inserts it into the list
214 referenced by head_new before the element listelm. If listelm value is
215 TOID_NULL, the object is inserted at the head of the list. The field
216 and field_new arguments are the names of the fields of type
217 POBJ_LIST_ENTRY in the element structure that are used to connect the
218 elements in both lists.
219
221 queue(3), libpmemobj(7) and <https://pmem.io>
222PMDK - 2023-06-05 ()