1PMEMOBJ_LIST_INSERT(3) PMDK Programmer's Manual PMEMOBJ_LIST_INSERT(3)
2
6 pmemobj_list_insert(), pmemobj_list_insert_new(), pmemobj_list_move(),
7 pmemobj_list_remove() - non-transactional persistent atomic lists func‐
8 tions
9
11 #include <libpmemobj.h>
12 int pmemobj_list_insert(PMEMobjpool *pop, size_t pe_offset, void *head,
14 PMEMoid dest, int before, PMEMoid oid);
15 PMEMoid pmemobj_list_insert_new(PMEMobjpool *pop, size_t pe_offset,
17 void *head, PMEMoid dest, int before, size_t size,
18 uint64_t type_num, pmemobj_constr constructor, void arg);
19 int pmemobj_list_move(PMEMobjpool *pop,
21 size_t pe_old_offset, void *head_old,
22 size_t pe_new_offset, void *head_new,
23 PMEMoid dest, int before, PMEMoid oid);
24 int pmemobj_list_remove(PMEMobjpool *pop, size_t pe_offset,
26 void *head, PMEMoid oid, int free);
27
29 In addition to the container operations on internal object collections
30 described in pmemobj_first(3), libpmemobj(7) provides a mechanism for
31 organizing persistent objects in user-defined, persistent, atomic, cir‐
32 cular, doubly-linked lists. All the routines and macros operating on
33 the persistent lists provide atomicity with respect to any power-fail
34 interruptions. If any of those operations is torn by program failure
35 or system crash, on recovery they are guaranteed to be entirely com‐
36 pleted or discarded, leaving the lists, persistent memory heap and in‐
37 ternal object containers in a consistent state.
38 The persistent atomic circular doubly linked lists support the follow‐
40 ing functionality:
41 • Insertion of an object at the head of the list, or at the end of the
43 list.
44 • Insertion of an object before or after any element in the list.
46 • Atomic allocation and insertion of a new object at the head of the
48 list, or at the end of the list.
49 • Atomic allocation and insertion of a new object before or after any
51 element in the list.
52 • Atomic moving of an element from one list to the specific location on
54 another list.
55 • Removal of any object in the list.
57 • Atomic removal and freeing of any object in the list.
59 • Forward or backward traversal through the list.
61 A list is headed by a list_head structure containing the object handle
63 of the first element on the list. The elements are doubly linked so
64 that an arbitrary element can be removed without the need to traverse
65 the list. New elements can be added to the list before or after an ex‐
66 isting element, at the head of the list, or at the tail of the list. A
67 list may be traversed in either direction.
68 The user-defined structure of each element must contain a field of type
70 list_entry that holds the object handles to the previous and next ele‐
71 ment on the list. Both the list_head and the list_entry structures are
72 declared in <libpmemobj.h>.
73 The functions below are intended to be used outside transactions -
75 transactional variants are described in manpages to functions mentioned
76 at TRANSACTIONAL OBJECT MANIPULATION in libpmemobj(7). Note that oper‐
77 ations performed using this non-transactional API are independent from
78 their transactional counterparts. If any non-transactional allocations
79 or list manipulations are performed within an open transaction, the
80 changes will not be rolled back if such a transaction is aborted or in‐
81 terrupted.
82 The list insertion and move functions use a common set of arguments to
84 define where an object will be inserted into the list. dest identifies
85 the element before or after which the object will be inserted, or, if
86 dest is OID_NULL, indicates that the object should be inserted at the
87 head or tail of the list. before determines where the object will be
88 inserted:
89 • POBJ_LIST_DEST_BEFORE - insert the element before the existing ele‐
91 ment dest
92 • POBJ_LIST_DEST_AFTER - insert the element after the existing element
94 dest
95 • POBJ_LIST_DEST_HEAD - when dest is OID_NULL, insert the element at
97 the head of the list
98 • POBJ_LIST_DEST_TAIL - when dest is OID_NULL, insert the element at
100 the tail of the list
101 NOTE: Earlier versions of libpmemobj(7) do not define
103 POBJ_LIST_DEST_BEFORE and POBJ_LIST_DEST_AFTER. Use 1 for before,
104 and 0 for after.
105 The pmemobj_list_insert() function inserts the element represented by
107 object handle oid into the list referenced by head, at the location
108 specified by dest and before as described above. pe_offset specifies
109 the offset of the structure that connects the elements in the list.
110 All the handles head, dest and oid must point to objects allocated from
111 memory pool pop. head and oid cannot be OID_NULL.
112 The pmemobj_list_insert_new() function atomically allocates a new ob‐
114 ject of given size and type type_num and inserts it into the list ref‐
115 erenced by head at the location specified by dest and before as de‐
116 scribed above. pe_offset specifies the offset of the structure that
117 connects the elements in the list. The handles head and dest must
118 point to objects allocated from memory pool pop. Before returning,
119 pmemobj_list_insert_new() calls the constructor function, passing the
120 pool handle pop, the pointer to the newly allocated object ptr, and the
121 arg argument. It is guaranteed that the allocated object is either
122 properly initialized or, if the allocation is interrupted before the
123 constructor completes, the memory space reserved for the object is re‐
124 claimed. head cannot be OID_NULL. The allocated object is also added
125 to the internal container associated with type_num, as described in
126 POBJ_FOREACH(3).
127 The pmemobj_list_move() function moves the object represented by object
129 handle oid from the list referenced by head_old to the list referenced
130 by head_new, inserting it at the location specified by dest and before
131 as described above. pe_old_offset and pe_new_offset specify the off‐
132 sets of the structures that connect the elements in the old and new
133 lists, respectively. All the handles head_old, head_new, dest and oid
134 must point to objects allocated from memory pool pop. head_old,
135 head_new and oid cannot be OID_NULL.
136 The pmemobj_list_remove() function removes the object represented by
138 object handle oid from the list referenced by head. If free is set, it
139 also removes the object from the internal object container and frees
140 the associated memory space. pe_offset specifies the offset of the
141 structure that connects the elements in the list. Both head and oid
142 must point to objects allocated from memory pool pop and cannot be
143 OID_NULL.
144
146 On success, pmemobj_list_insert(), pmemobj_list_remove() and pmemo‐
147 bj_list_move() return 0. On error, they return -1 and set errno appro‐
148 priately.
149 On success, pmemobj_list_insert_new() returns a handle to the newly al‐
151 located object. If the constructor returns a non-zero value, the allo‐
152 cation is canceled, -1 is returned, and errno is set to ECANCELED. On
153 other errors, OID_NULL is returned and errno is set appropriately.
154
156 pmemobj_first(3), POBJ_FOREACH(3), libpmemobj(7) and <https://pmem.io>
157PMDK - pmemobj API version 2.3 2021-09-24 PMEMOBJ_LIST_INSERT(3)