.\" Automatically generated by Pandoc 2.1.3
.\"
.TH "POBJ_LIST_HEAD" "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]POBJ_LIST_HEAD\f[](), \f[B]POBJ_LIST_ENTRY\f[](),
\f[B]POBJ_LIST_FIRST\f[](), \f[B]POBJ_LIST_LAST\f[](),
\f[B]POBJ_LIST_EMPTY\f[](), \f[B]POBJ_LIST_NEXT\f[](),
\f[B]POBJ_LIST_PREV\f[](),
.PP
\f[B]POBJ_LIST_FOREACH\f[](), \f[B]POBJ_LIST_FOREACH_REVERSE\f[](),
.PP
\f[B]POBJ_LIST_INSERT_HEAD\f[](), \f[B]POBJ_LIST_INSERT_TAIL\f[](),
\f[B]POBJ_LIST_INSERT_AFTER\f[](), \f[B]POBJ_LIST_INSERT_BEFORE\f[](),
\f[B]POBJ_LIST_INSERT_NEW_HEAD\f[](),
\f[B]POBJ_LIST_INSERT_NEW_TAIL\f[](),
\f[B]POBJ_LIST_INSERT_NEW_AFTER\f[](),
\f[B]POBJ_LIST_INSERT_NEW_BEFORE\f[](),
.PP
\f[B]POBJ_LIST_REMOVE\f[](), \f[B]POBJ_LIST_REMOVE_FREE\f[](),
.PP
\f[B]POBJ_LIST_MOVE_ELEMENT_HEAD\f[](),
\f[B]POBJ_LIST_MOVE_ELEMENT_TAIL\f[](),
\f[B]POBJ_LIST_MOVE_ELEMENT_AFTER\f[](),
\f[B]POBJ_LIST_MOVE_ELEMENT_BEFORE\f[]() \- type\-safe
non\-transactional persistent atomic lists
.SH SYNOPSIS
.IP
.nf
\f[C]
#include\ <libpmemobj.h>

POBJ_LIST_HEAD(HEADNAME,\ TYPE)
POBJ_LIST_ENTRY(TYPE)
POBJ_LIST_FIRST(POBJ_LIST_HEAD\ *head)
POBJ_LIST_LAST(POBJ_LIST_HEAD\ *head,\ POBJ_LIST_ENTRY\ FIELD)
POBJ_LIST_EMPTY(POBJ_LIST_HEAD\ *head)
POBJ_LIST_NEXT(TOID\ elm,\ POBJ_LIST_ENTRY\ FIELD)
POBJ_LIST_PREV(TOID\ elm,\ POBJ_LIST_ENTRY\ FIELD)

POBJ_LIST_FOREACH(TOID\ var,\ POBJ_LIST_HEAD\ *head,\ POBJ_LIST_ENTRY\ FIELD)
POBJ_LIST_FOREACH_REVERSE(TOID\ var,\ POBJ_LIST_HEAD\ *head,\ POBJ_LIST_ENTRY\ FIELD)

POBJ_LIST_INSERT_HEAD(PMEMobjpool\ *pop,\ POBJ_LIST_HEAD\ *head,
\ \ \ \ TOID\ elm,\ POBJ_LIST_ENTRY\ FIELD)
POBJ_LIST_INSERT_TAIL(PMEMobjpool\ *pop,\ POBJ_LIST_HEAD\ *head,
\ \ \ \ TOID\ elm,\ POBJ_LIST_ENTRY\ FIELD)
POBJ_LIST_INSERT_AFTER(PMEMobjpool\ *pop,\ POBJ_LIST_HEAD\ *head,
\ \ \ \ TOID\ listelm,\ TOID\ elm,\ POBJ_LIST_ENTRY\ FIELD)
POBJ_LIST_INSERT_BEFORE(PMEMobjpool\ *pop,\ POBJ_LIST_HEAD\ *head,
\ \ \ \ TOID\ listelm,\ TOID\ elm,\ POBJ_LIST_ENTRY\ FIELD)
POBJ_LIST_INSERT_NEW_HEAD(PMEMobjpool\ *pop,\ POBJ_LIST_HEAD\ *head,
\ \ \ \ POBJ_LIST_ENTRY\ FIELD,\ size_t\ size,
\ \ \ \ pmemobj_constr\ constructor,\ void\ *arg)
POBJ_LIST_INSERT_NEW_TAIL(PMEMobjpool\ *pop,\ POBJ_LIST_HEAD\ *head,
\ \ \ \ POBJ_LIST_ENTRY\ FIELD,\ size_t\ size,
\ \ \ \ pmemobj_constr\ constructor,\ void\ *arg)
POBJ_LIST_INSERT_NEW_AFTER(PMEMobjpool\ *pop,\ POBJ_LIST_HEAD\ *head,
\ \ \ \ TOID\ listelm,\ POBJ_LIST_ENTRY\ FIELD,\ size_t\ size,
\ \ \ \ pmemobj_constr\ constructor,\ void\ *arg)
POBJ_LIST_INSERT_NEW_BEFORE(PMEMobjpool\ *pop,\ POBJ_LIST_HEAD\ *head,
\ \ \ \ TOID\ listelm,\ POBJ_LIST_ENTRY\ FIELD,\ size_t\ size,
\ \ \ \ pmemobj_constr\ constructor,\ void\ *arg)

POBJ_LIST_REMOVE(PMEMobjpool\ *pop,\ POBJ_LIST_HEAD\ *head,
\ \ \ \ TOID\ elm,\ POBJ_LIST_ENTRY\ FIELD)
POBJ_LIST_REMOVE_FREE(PMEMobjpool\ *pop,\ POBJ_LIST_HEAD\ *head,
\ \ \ \ TOID\ elm,\ POBJ_LIST_ENTRY\ FIELD)

POBJ_LIST_MOVE_ELEMENT_HEAD(PMEMobjpool\ *pop,\ POBJ_LIST_HEAD\ *head,
\ \ \ \ POBJ_LIST_HEAD\ *head_new,\ TOID\ elm,\ POBJ_LIST_ENTRY\ FIELD,
\ \ \ \ POBJ_LIST_ENTRY\ field_new)
POBJ_LIST_MOVE_ELEMENT_TAIL(PMEMobjpool\ *pop,\ POBJ_LIST_HEAD\ *head,
\ \ \ \ POBJ_LIST_HEAD\ *head_new,\ TOID\ elm,\ POBJ_LIST_ENTRY\ FIELD,
\ \ \ \ POBJ_LIST_ENTRY\ field_new)
POBJ_LIST_MOVE_ELEMENT_AFTER(PMEMobjpool\ *pop,\ POBJ_LIST_HEAD\ *head,
\ \ \ \ POBJ_LIST_HEAD\ *head_new,\ TOID\ listelm,\ TOID\ elm,
\ \ \ \ POBJ_LIST_ENTRY\ FIELD,\ POBJ_LIST_ENTRY\ field_new)
POBJ_LIST_MOVE_ELEMENT_BEFORE(PMEMobjpool\ *pop,\ POBJ_LIST_HEAD\ *head,
\ \ \ \ POBJ_LIST_HEAD\ *head_new,\ TOID\ listelm,\ TOID\ elm,
\ \ \ \ POBJ_LIST_ENTRY\ FIELD,\ POBJ_LIST_ENTRY\ field_new)
\f[]
.fi
.SH DESCRIPTION
.PP
The following macros define and operate on a type\-safe persistent
atomic circular doubly linked list data structure that consist of a set
of persistent objects of a well\-known type.
Unlike the functions described in the previous section, these macros
provide type enforcement by requiring declaration of type of the objects
stored in given list, and not allowing mixing objects of different types
in a single list.
.PP
The functionality and semantics of those macros is similar to circular
queues defined in \f[B]queue\f[](3).
.PP
The majority of the macros must specify the handle to the memory pool
\f[I]pop\f[] and the name of the \f[I]field\f[] in the user\-defined
structure, which must be of type \f[I]POBJ_LIST_ENTRY\f[] and is used to
connect the elements in the list.
.PP
A list is headed by a structure defined by the \f[B]POBJ_LIST_HEAD\f[]()
macro.
This structure contains an object handle of the first element on the
list.
The elements are doubly linked so that an arbitrary element can be
removed without a 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 end of the list.
A list may be traversed in either direction.
A \f[I]POBJ_LIST_HEAD\f[] structure is declared as follows:
.IP
.nf
\f[C]
#define\ POBJ_LIST_HEAD(HEADNAME,\ TYPE)
struct\ HEADNAME
{
\ \ \ \ TOID(TYPE)\ pe_first;
\ \ \ \ PMEMmutex\ lock;
};
\f[]
.fi
.PP
In the macro definitions, \f[I]TYPE\f[] is the name of a user\-defined
structure, that must contain a field of type \f[I]POBJ_LIST_ENTRY\f[].
The argument \f[I]HEADNAME\f[] is the name of a user\-defined structure
that must be declared using the macro \f[I]POBJ_LIST_HEAD\f[].
See the examples below for further explanation of how these macros are
used.
.PP
The macro \f[I]POBJ_LIST_ENTRY\f[] declares a structure that connects
the elements in the list.
.IP
.nf
\f[C]
#define\ POBJ_LIST_ENTRY(TYPE)
struct
{
\ \ \ \ TOID(TYPE)\ pe_next;
\ \ \ \ TOID(TYPE)\ pe_prev;
};
\f[]
.fi
.PP
The macro \f[B]POBJ_LIST_FIRST\f[]() returns the first element on the
list referenced by \f[I]head\f[].
If the list is empty \f[B]OID_NULL\f[] is returned.
.PP
The macro \f[B]POBJ_LIST_LAST\f[]() returns the last element on the list
referenced by \f[I]head\f[].
If the list is empty \f[B]OID_NULL\f[] is returned.
.PP
The macro \f[B]POBJ_LIST_EMPTY\f[]() evaluates to 1 if the list
referenced by \f[I]head\f[] is empty.
Otherwise, 0 is returned.
.PP
The macro \f[B]POBJ_LIST_NEXT\f[]() returns the element next to the
element \f[I]elm\f[].
.PP
The macro \f[B]POBJ_LIST_PREV\f[]() returns the element preceding the
element \f[I]elm\f[].
.PP
The macro \f[B]POBJ_LIST_FOREACH\f[]() traverses the list referenced by
\f[I]head\f[] assigning a handle to each element in turn to \f[I]var\f[]
variable.
.PP
The macro \f[B]POBJ_LIST_FOREACH_REVERSE\f[]() traverses the list
referenced by \f[I]head\f[] in reverse order, assigning a handle to each
element in turn to \f[I]var\f[] variable.
The \f[I]field\f[] argument is the name of the field of type
\f[I]POBJ_LIST_ENTRY\f[] in the element structure.
.PP
The macro \f[B]POBJ_LIST_INSERT_HEAD\f[]() inserts the element
\f[I]elm\f[] at the head of the list referenced by \f[I]head\f[].
.PP
The macro \f[B]POBJ_LIST_INSERT_TAIL\f[]() inserts the element
\f[I]elm\f[] at the end of the list referenced by \f[I]head\f[].
.PP
The macro \f[B]POBJ_LIST_INSERT_AFTER\f[]() inserts the element
\f[I]elm\f[] into the list referenced by \f[I]head\f[] after the element
\f[I]listelm\f[].
If \f[I]listelm\f[] value is \f[B]TOID_NULL\f[], the object is inserted
at the end of the list.
.PP
The macro \f[B]POBJ_LIST_INSERT_BEFORE\f[]() inserts the element
\f[I]elm\f[] into the list referenced by \f[I]head\f[] before the
element \f[I]listelm\f[].
If \f[I]listelm\f[] value is \f[B]TOID_NULL\f[], the object is inserted
at the head of the list.
.PP
The macro \f[B]POBJ_LIST_INSERT_NEW_HEAD\f[]() atomically allocates a
new object of size \f[I]size\f[] and inserts it at the head of the list
referenced by \f[I]head\f[].
The newly allocated object is also added to the internal object
container associated with a type number which is retrieved from the
typed \f[I]OID\f[] of the first element on list.
.PP
The macro \f[B]POBJ_LIST_INSERT_NEW_TAIL\f[]() atomically allocates a
new object of size \f[I]size\f[] and inserts it at the tail of the list
referenced by \f[I]head\f[].
The newly allocated object is also added to the internal object
container associated with with a type number which is retrieved from the
typed \f[I]OID\f[] of the first element on list.
.PP
The macro \f[B]POBJ_LIST_INSERT_NEW_AFTER\f[]() atomically allocates a
new object of size \f[I]size\f[] and inserts it into the list referenced
by \f[I]head\f[] after the element \f[I]listelm\f[].
If \f[I]listelm\f[] value is \f[B]TOID_NULL\f[], the object is inserted
at the end of the list.
The newly allocated object is also added to the internal object
container associated with with a type number which is retrieved from the
typed \f[I]OID\f[] of the first element on list.
.PP
The macro \f[B]POBJ_LIST_INSERT_NEW_BEFORE\f[]() atomically allocates a
new object of size \f[I]size\f[] and inserts it into the list referenced
by \f[I]head\f[] before the element \f[I]listelm\f[].
If \f[I]listelm\f[] value is \f[B]TOID_NULL\f[], the object is inserted
at the head of the list.
The newly allocated object is also added to the internal object
container associated with with a type number which is retrieved from the
typed \f[I]OID\f[] of the first element on list.
.PP
The macro \f[B]POBJ_LIST_REMOVE\f[]() removes the element \f[I]elm\f[]
from the list referenced by \f[I]head\f[].
.PP
The macro \f[B]POBJ_LIST_REMOVE_FREE\f[]() removes the element
\f[I]elm\f[] from the list referenced by \f[I]head\f[] and frees the
memory space represented by this element.
.PP
The macro \f[B]POBJ_LIST_MOVE_ELEMENT_HEAD\f[]() moves the element
\f[I]elm\f[] from the list referenced by \f[I]head\f[] to the head of
the list \f[I]head_new\f[].
The \f[I]field\f[] and \f[I]field_new\f[] arguments are the names of the
fields of type \f[I]POBJ_LIST_ENTRY\f[] in the element structure that
are used to connect the elements in both lists.
.PP
The macro \f[B]POBJ_LIST_MOVE_ELEMENT_TAIL\f[]() moves the element
\f[I]elm\f[] from the list referenced by \f[I]head\f[] to the end of the
list \f[I]head_new\f[].
The \f[I]field\f[] and \f[I]field_new\f[] arguments are the names of the
fields of type \f[I]POBJ_LIST_ENTRY\f[] in the element structure that
are used to connect the elements in both lists.
.PP
The macro \f[B]POBJ_LIST_MOVE_ELEMENT_AFTER\f[]() atomically removes the
element \f[I]elm\f[] from the list referenced by \f[I]head\f[] and
inserts it into the list referenced by \f[I]head_new\f[] after the
element \f[I]listelm\f[].
If \f[I]listelm\f[] value is \f[I]TOID_NULL\f[], the object is inserted
at the end of the list.
The \f[I]field\f[] and \f[I]field_new\f[] arguments are the names of the
fields of type \f[I]POBJ_LIST_ENTRY\f[] in the element structure that
are used to connect the elements in both lists.
.PP
The macro \f[B]POBJ_LIST_MOVE_ELEMENT_BEFORE\f[]() atomically removes
the element \f[I]elm\f[] from the list referenced by \f[I]head\f[] and
inserts it into the list referenced by \f[I]head_new\f[] before the
element \f[I]listelm\f[].
If \f[I]listelm\f[] value is \f[B]TOID_NULL\f[], the object is inserted
at the head of the list.
The \f[I]field\f[] and \f[I]field_new\f[] arguments are the names of the
fields of type \f[I]POBJ_LIST_ENTRY\f[] in the element structure that
are used to connect the elements in both lists.
.SH SEE ALSO
.PP
\f[B]queue\f[](3), \f[B]libpmemobj\f[](7) and \f[B]<http://pmem.io>\f[]