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

NAME

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
10       POBJ_LIST_FOREACH(), POBJ_LIST_FOREACH_REVERSE(),
11
12       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
17       POBJ_LIST_REMOVE(), POBJ_LIST_REMOVE_FREE(),
18
19       POBJ_LIST_MOVE_ELEMENT_HEAD(),           POBJ_LIST_MOVE_ELEMENT_TAIL(),
20       POBJ_LIST_MOVE_ELEMENT_AFTER(),    POBJ_LIST_MOVE_ELEMENT_BEFORE()    -
21       type-safe non-transactional persistent atomic lists
22

SYNOPSIS

24              #include <libpmemobj.h>
25
26              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
34              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
37              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
58              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
63              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

DESCRIPTION

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
84       The  functionality and semantics of those macros is similar to circular
85       queues defined in queue(3).
86
87       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
92       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
100              #define POBJ_LIST_HEAD(HEADNAME, TYPE)
101              struct HEADNAME
102              {
103                  TOID(TYPE) pe_first;
104                  PMEMmutex lock;
105              };
106
107       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
113       The  macro  POBJ_LIST_ENTRY declares a structure that connects the ele‐
114       ments in the list.
115
116              #define POBJ_LIST_ENTRY(TYPE)
117              struct
118              {
119                  TOID(TYPE) pe_next;
120                  TOID(TYPE) pe_prev;
121              };
122
123       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
126       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
129       The macro POBJ_LIST_EMPTY() evaluates to 1 if the  list  referenced  by
130       head is empty.  Otherwise, 0 is returned.
131
132       The macro POBJ_LIST_NEXT() returns the element next to the element elm.
133
134       The  macro  POBJ_LIST_PREV()  returns the element preceding the element
135       elm.
136
137       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
140       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
145       The macro POBJ_LIST_INSERT_HEAD() inserts the element elm at  the  head
146       of the list referenced by head.
147
148       The macro POBJ_LIST_INSERT_TAIL() inserts the element elm at the end of
149       the list referenced by head.
150
151       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
155       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
159       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
165       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 with a type number which is retrieved from the
169       typed OID of the first element on list.
170
171       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
178       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
185       The macro POBJ_LIST_REMOVE() removes the element elm from the list ref‐
186       erenced by head.
187
188       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
192       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
198       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
204       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
212       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

SEE ALSO

221       queue(3), libpmemobj(7) and <http://pmem.io>
222
223
224
225PMDK - pmemobj API version 2.3    2018-07-18                 POBJ_LIST_HEAD(3)
Impressum