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

NAME

6       pmemobj_list_insert(),  pmemobj_list_insert_new(), pmemobj_list_move(),
7       pmemobj_list_remove() - non-transactional persistent atomic lists func‐
8       tions
9

SYNOPSIS

11              #include <libpmemobj.h>
12
13              int pmemobj_list_insert(PMEMobjpool *pop, size_t pe_offset, void *head,
14                  PMEMoid dest, int before, PMEMoid oid);
15
16              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
20              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
25              int pmemobj_list_remove(PMEMobjpool *pop, size_t pe_offset,
26                  void *head, PMEMoid oid, int free);
27

DESCRIPTION

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
39       The  persistent atomic circular doubly linked lists support the follow‐
40       ing functionality:
41
42       • Insertion of an object at the head of the list, or at the end of  the
43         list.
44
45       • Insertion of an object before or after any element in the list.
46
47       • Atomic  allocation  and  insertion of a new object at the head of the
48         list, or at the end of the list.
49
50       • Atomic allocation and insertion of a new object before or  after  any
51         element in the list.
52
53       • Atomic moving of an element from one list to the specific location on
54         another list.
55
56       • Removal of any object in the list.
57
58       • Atomic removal and freeing of any object in the list.
59
60       • Forward or backward traversal through the list.
61
62       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
69       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
74       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
83       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
90POBJ_LIST_DEST_BEFORE - insert the element before the  existing  ele‐
91         ment dest
92
93POBJ_LIST_DEST_AFTER  - insert the element after the existing element
94         dest
95
96POBJ_LIST_DEST_HEAD - when dest is OID_NULL, insert  the  element  at
97         the head of the list
98
99POBJ_LIST_DEST_TAIL  -  when  dest is OID_NULL, insert the element at
100         the tail of the list
101
102         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
106       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
113       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
128       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
137       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

RETURN VALUE

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
150       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

SEE ALSO

156       pmemobj_first(3), POBJ_FOREACH(3), libpmemobj(7) and <https://pmem.io>
157
158
159
160PMDK - pmemobj API version 2.3    2021-09-24            PMEMOBJ_LIST_INSERT(3)
Impressum