.\" Automatically generated by Pandoc 2.1.3
.\"
.TH "PMEMOBJ_LIST_INSERT" "3" "2018-07-18" "PMDK - pmemobj API version 2.3" "PMDK Programmer's Manual"
.hy
.\" Copyright 2014-2018, Intel Corporation
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\"     * Redistributions of source code must retain the above copyright
.\"       notice, this list of conditions and the following disclaimer.
.\"
.\"     * Redistributions in binary form must reproduce the above copyright
.\"       notice, this list of conditions and the following disclaimer in
.\"       the documentation and/or other materials provided with the
.\"       distribution.
.\"
.\"     * Neither the name of the copyright holder nor the names of its
.\"       contributors may be used to endorse or promote products derived
.\"       from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
.\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.SH NAME
.PP
\f[B]pmemobj_list_insert\f[](), \f[B]pmemobj_list_insert_new\f[](),
\f[B]pmemobj_list_move\f[](), \f[B]pmemobj_list_remove\f[]() \-
non\-transactional persistent atomic lists functions
.SH SYNOPSIS
.IP
.nf
\f[C]
#include\ <libpmemobj.h>

int\ pmemobj_list_insert(PMEMobjpool\ *pop,\ size_t\ pe_offset,\ void\ *head,
\ \ \ \ PMEMoid\ dest,\ int\ before,\ PMEMoid\ oid);

PMEMoid\ pmemobj_list_insert_new(PMEMobjpool\ *pop,\ size_t\ pe_offset,
\ \ \ \ void\ *head,\ PMEMoid\ dest,\ int\ before,\ size_t\ size,
\ \ \ \ uint64_t\ type_num,\ pmemobj_constr\ constructor,\ void\ arg);

int\ pmemobj_list_move(PMEMobjpool\ *pop,
\ \ \ \ size_t\ pe_old_offset,\ void\ *head_old,
\ \ \ \ size_t\ pe_new_offset,\ void\ *head_new,
\ \ \ \ PMEMoid\ dest,\ int\ before,\ PMEMoid\ oid);

int\ pmemobj_list_remove(PMEMobjpool\ *pop,\ size_t\ pe_offset,
\ \ \ \ void\ *head,\ PMEMoid\ oid,\ int\ free);
\f[]
.fi
.SH DESCRIPTION
.PP
In addition to the container operations on internal object collections
described in \f[B]pmemobj_first\f[](3), \f[B]libpmemobj\f[](7) provides
a mechanism for organizing persistent objects in user\-defined,
persistent, atomic, circular, doubly\-linked lists.
All the routines and macros operating on the persistent lists provide
atomicity with respect to any power\-fail interruptions.
If any of those operations is torn by program failure or system crash,
on recovery they are guaranteed to be entirely completed or discarded,
leaving the lists, persistent memory heap and internal object containers
in a consistent state.
.PP
The persistent atomic circular doubly linked lists support the following
functionality:
.IP \[bu] 2
Insertion of an object at the head of the list, or at the end of the
list.
.IP \[bu] 2
Insertion of an object before or after any element in the list.
.IP \[bu] 2
Atomic allocation and insertion of a new object at the head of the list,
or at the end of the list.
.IP \[bu] 2
Atomic allocation and insertion of a new object before or after any
element in the list.
.IP \[bu] 2
Atomic moving of an element from one list to the specific location on
another list.
.IP \[bu] 2
Removal of any object in the list.
.IP \[bu] 2
Atomic removal and freeing of any object in the list.
.IP \[bu] 2
Forward or backward traversal through the list.
.PP
A list is headed by a \f[I]list_head\f[] structure containing the object
handle of the first element on the list.
The elements are doubly linked so that an arbitrary element can be
removed without the need to traverse the list.
New elements can be added to the list before or after an existing
element, at the head of the list, or at the tail of the list.
A list may be traversed in either direction.
.PP
The user\-defined structure of each element must contain a field of type
\f[I]list_entry\f[] that holds the object handles to the previous and
next element on the list.
Both the \f[I]list_head\f[] and the \f[I]list_entry\f[] structures are
declared in \f[B]<libpmemobj.h>\f[].
.PP
The functions below are intended to be used outside transactions \-
transactional variants are described in manpages to functions mentioned
at \f[B]TRANSACTIONAL OBJECT MANIPULATION\f[] in \f[B]libpmemobj\f[](7).
Note that operations performed using this non\-transactional API are
independent from their transactional counterparts.
If any non\-transactional allocations or list manipulations are
performed within an open transaction, the changes will not be rolled
back if such a transaction is aborted or interrupted.
.PP
The list insertion and move functions use a common set of arguments to
define where an object will be inserted into the list.
\f[I]dest\f[] identifies the element before or after which the object
will be inserted, or, if \f[I]dest\f[] is \f[B]OID_NULL\f[], indicates
that the object should be inserted at the head or tail of the list.
\f[I]before\f[] determines where the object will be inserted:
.IP \[bu] 2
\f[B]POBJ_LIST_DEST_BEFORE\f[] \- insert the element before the existing
element \f[I]dest\f[]
.IP \[bu] 2
\f[B]POBJ_LIST_DEST_AFTER\f[] \- insert the element after the existing
element \f[I]dest\f[]
.IP \[bu] 2
\f[B]POBJ_LIST_DEST_HEAD\f[] \- when \f[I]dest\f[] is \f[B]OID_NULL\f[],
insert the element at the head of the list
.IP \[bu] 2
\f[B]POBJ_LIST_DEST_TAIL\f[] \- when \f[I]dest\f[] is \f[B]OID_NULL\f[],
insert the element at the tail of the list
.RS
.PP
NOTE: Earlier versions of \f[B]libpmemobj\f[](7) do not define
\f[B]POBJ_LIST_DEST_BEFORE\f[] and \f[B]POBJ_LIST_DEST_AFTER\f[].
Use 1 for before, and 0 for after.
.RE
.PP
The \f[B]pmemobj_list_insert\f[]() function inserts the element
represented by object handle \f[I]oid\f[] into the list referenced by
\f[I]head\f[], at the location specified by \f[I]dest\f[] and
\f[I]before\f[] as described above.
\f[I]pe_offset\f[] specifies the offset of the structure that connects
the elements in the list.
All the handles \f[I]head\f[], \f[I]dest\f[] and \f[I]oid\f[] must point
to objects allocated from memory pool \f[I]pop\f[].
\f[I]head\f[] and \f[I]oid\f[] cannot be \f[B]OID_NULL\f[].
.PP
The \f[B]pmemobj_list_insert_new\f[]() function atomically allocates a
new object of given \f[I]size\f[] and type \f[I]type_num\f[] and inserts
it into the list referenced by \f[I]head\f[] at the location specified
by \f[I]dest\f[] and \f[I]before\f[] as described above.
\f[I]pe_offset\f[] specifies the offset of the structure that connects
the elements in the list.
The handles \f[I]head\f[] and \f[I]dest\f[] must point to objects
allocated from memory pool \f[I]pop\f[].
Before returning, \f[B]pmemobj_list_insert_new\f[]() calls the
\f[I]constructor\f[] function, passing the pool handle \f[I]pop\f[], the
pointer to the newly allocated object \f[I]ptr\f[], and the \f[I]arg\f[]
argument.
It is guaranteed that the allocated object is either properly
initialized or, if the allocation is interrupted before the constructor
completes, the memory space reserved for the object is reclaimed.
\f[I]head\f[] cannot be \f[B]OID_NULL\f[].
The allocated object is also added to the internal container associated
with \f[I]type_num\f[], as described in \f[B]POBJ_FOREACH\f[](3).
.PP
The \f[B]pmemobj_list_move\f[]() function moves the object represented
by object handle \f[I]oid\f[] from the list referenced by
\f[I]head_old\f[] to the list referenced by \f[I]head_new\f[], inserting
it at the location specified by \f[I]dest\f[] and \f[I]before\f[] as
described above.
\f[I]pe_old_offset\f[] and \f[I]pe_new_offset\f[] specify the offsets of
the structures that connect the elements in the old and new lists,
respectively.
All the handles \f[I]head_old\f[], \f[I]head_new\f[], \f[I]dest\f[] and
\f[I]oid\f[] must point to objects allocated from memory pool
\f[I]pop\f[].
\f[I]head_old\f[], \f[I]head_new\f[] and \f[I]oid\f[] cannot be
\f[B]OID_NULL\f[].
.PP
The \f[B]pmemobj_list_remove\f[]() function removes the object
represented by object handle \f[I]oid\f[] from the list referenced by
\f[I]head\f[].
If \f[I]free\f[] is set, it also removes the object from the internal
object container and frees the associated memory space.
\f[I]pe_offset\f[] specifies the offset of the structure that connects
the elements in the list.
Both \f[I]head\f[] and \f[I]oid\f[] must point to objects allocated from
memory pool \f[I]pop\f[] and cannot be \f[B]OID_NULL\f[].
.SH RETURN VALUE
.PP
On success, \f[B]pmemobj_list_insert\f[](),
\f[B]pmemobj_list_remove\f[]() and \f[B]pmemobj_list_move\f[]() return
0.
On error, they return \-1 and set \f[I]errno\f[] appropriately.
.PP
On success, \f[B]pmemobj_list_insert_new\f[]() returns a handle to the
newly allocated object.
If the constructor returns a non\-zero value, the allocation is
canceled, \-1 is returned, and \f[I]errno\f[] is set to
\f[B]ECANCELED\f[].
On other errors, \f[B]OID_NULL\f[] is returned and \f[I]errno\f[] is set
appropriately.
.SH SEE ALSO
.PP
\f[B]pmemobj_first\f[](3), \f[B]POBJ_FOREACH\f[](3),
\f[B]libpmemobj\f[](7) and \f[B]<http://pmem.io>\f[]