.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "" "" "2023-05-31" "PMDK - " "PMDK Programmer's Manual"
.hy
.\" SPDX-License-Identifier: BSD-3-Clause
.\" Copyright 2017-2018, Intel Corporation
.SH NAME
.PP
\f[B]POBJ_LIST_HEAD\f[R](), \f[B]POBJ_LIST_ENTRY\f[R](),
\f[B]POBJ_LIST_FIRST\f[R](), \f[B]POBJ_LIST_LAST\f[R](),
\f[B]POBJ_LIST_EMPTY\f[R](), \f[B]POBJ_LIST_NEXT\f[R](),
\f[B]POBJ_LIST_PREV\f[R](),
.PP
\f[B]POBJ_LIST_FOREACH\f[R](), \f[B]POBJ_LIST_FOREACH_REVERSE\f[R](),
.PP
\f[B]POBJ_LIST_INSERT_HEAD\f[R](), \f[B]POBJ_LIST_INSERT_TAIL\f[R](),
\f[B]POBJ_LIST_INSERT_AFTER\f[R](), \f[B]POBJ_LIST_INSERT_BEFORE\f[R](),
\f[B]POBJ_LIST_INSERT_NEW_HEAD\f[R](),
\f[B]POBJ_LIST_INSERT_NEW_TAIL\f[R](),
\f[B]POBJ_LIST_INSERT_NEW_AFTER\f[R](),
\f[B]POBJ_LIST_INSERT_NEW_BEFORE\f[R](),
.PP
\f[B]POBJ_LIST_REMOVE\f[R](), \f[B]POBJ_LIST_REMOVE_FREE\f[R](),
.PP
\f[B]POBJ_LIST_MOVE_ELEMENT_HEAD\f[R](),
\f[B]POBJ_LIST_MOVE_ELEMENT_TAIL\f[R](),
\f[B]POBJ_LIST_MOVE_ELEMENT_AFTER\f[R](),
\f[B]POBJ_LIST_MOVE_ELEMENT_BEFORE\f[R]() - 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[R]
.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[R](3).
.PP
The majority of the macros must specify the handle to the memory pool
\f[I]pop\f[R] and the name of the \f[I]field\f[R] in the user-defined
structure, which must be of type \f[I]POBJ_LIST_ENTRY\f[R] 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[R]() 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[R] structure is declared as follows:
.IP
.nf
\f[C]
#define POBJ_LIST_HEAD(HEADNAME, TYPE)
struct HEADNAME
{
    TOID(TYPE) pe_first;
    PMEMmutex lock;
};
\f[R]
.fi
.PP
In the macro definitions, \f[I]TYPE\f[R] is the name of a user-defined
structure, that must contain a field of type \f[I]POBJ_LIST_ENTRY\f[R].
The argument \f[I]HEADNAME\f[R] is the name of a user-defined structure
that must be declared using the macro \f[I]POBJ_LIST_HEAD\f[R].
See the examples below for further explanation of how these macros are
used.
.PP
The macro \f[I]POBJ_LIST_ENTRY\f[R] 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[R]
.fi
.PP
The macro \f[B]POBJ_LIST_FIRST\f[R]() returns the first element on the
list referenced by \f[I]head\f[R].
If the list is empty \f[B]OID_NULL\f[R] is returned.
.PP
The macro \f[B]POBJ_LIST_LAST\f[R]() returns the last element on the
list referenced by \f[I]head\f[R].
If the list is empty \f[B]OID_NULL\f[R] is returned.
.PP
The macro \f[B]POBJ_LIST_EMPTY\f[R]() evaluates to 1 if the list
referenced by \f[I]head\f[R] is empty.
Otherwise, 0 is returned.
.PP
The macro \f[B]POBJ_LIST_NEXT\f[R]() returns the element next to the
element \f[I]elm\f[R].
.PP
The macro \f[B]POBJ_LIST_PREV\f[R]() returns the element preceding the
element \f[I]elm\f[R].
.PP
The macro \f[B]POBJ_LIST_FOREACH\f[R]() traverses the list referenced by
\f[I]head\f[R] assigning a handle to each element in turn to
\f[I]var\f[R] variable.
.PP
The macro \f[B]POBJ_LIST_FOREACH_REVERSE\f[R]() traverses the list
referenced by \f[I]head\f[R] in reverse order, assigning a handle to
each element in turn to \f[I]var\f[R] variable.
The \f[I]field\f[R] argument is the name of the field of type
\f[I]POBJ_LIST_ENTRY\f[R] in the element structure.
.PP
The macro \f[B]POBJ_LIST_INSERT_HEAD\f[R]() inserts the element
\f[I]elm\f[R] at the head of the list referenced by \f[I]head\f[R].
.PP
The macro \f[B]POBJ_LIST_INSERT_TAIL\f[R]() inserts the element
\f[I]elm\f[R] at the end of the list referenced by \f[I]head\f[R].
.PP
The macro \f[B]POBJ_LIST_INSERT_AFTER\f[R]() inserts the element
\f[I]elm\f[R] into the list referenced by \f[I]head\f[R] after the
element \f[I]listelm\f[R].
If \f[I]listelm\f[R] value is \f[B]TOID_NULL\f[R], the object is
inserted at the end of the list.
.PP
The macro \f[B]POBJ_LIST_INSERT_BEFORE\f[R]() inserts the element
\f[I]elm\f[R] into the list referenced by \f[I]head\f[R] before the
element \f[I]listelm\f[R].
If \f[I]listelm\f[R] value is \f[B]TOID_NULL\f[R], the object is
inserted at the head of the list.
.PP
The macro \f[B]POBJ_LIST_INSERT_NEW_HEAD\f[R]() atomically allocates a
new object of size \f[I]size\f[R] and inserts it at the head of the list
referenced by \f[I]head\f[R].
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[R] of the first element on list.
.PP
The macro \f[B]POBJ_LIST_INSERT_NEW_TAIL\f[R]() atomically allocates a
new object of size \f[I]size\f[R] and inserts it at the tail of the list
referenced by \f[I]head\f[R].
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[R] of the first element on list.
.PP
The macro \f[B]POBJ_LIST_INSERT_NEW_AFTER\f[R]() atomically allocates a
new object of size \f[I]size\f[R] and inserts it into the list
referenced by \f[I]head\f[R] after the element \f[I]listelm\f[R].
If \f[I]listelm\f[R] value is \f[B]TOID_NULL\f[R], 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[R] of the first element on list.
.PP
The macro \f[B]POBJ_LIST_INSERT_NEW_BEFORE\f[R]() atomically allocates a
new object of size \f[I]size\f[R] and inserts it into the list
referenced by \f[I]head\f[R] before the element \f[I]listelm\f[R].
If \f[I]listelm\f[R] value is \f[B]TOID_NULL\f[R], 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[R] of the first element on list.
.PP
The macro \f[B]POBJ_LIST_REMOVE\f[R]() removes the element \f[I]elm\f[R]
from the list referenced by \f[I]head\f[R].
.PP
The macro \f[B]POBJ_LIST_REMOVE_FREE\f[R]() removes the element
\f[I]elm\f[R] from the list referenced by \f[I]head\f[R] and frees the
memory space represented by this element.
.PP
The macro \f[B]POBJ_LIST_MOVE_ELEMENT_HEAD\f[R]() moves the element
\f[I]elm\f[R] from the list referenced by \f[I]head\f[R] to the head of
the list \f[I]head_new\f[R].
The \f[I]field\f[R] and \f[I]field_new\f[R] arguments are the names of
the fields of type \f[I]POBJ_LIST_ENTRY\f[R] 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[R]() moves the element
\f[I]elm\f[R] from the list referenced by \f[I]head\f[R] to the end of
the list \f[I]head_new\f[R].
The \f[I]field\f[R] and \f[I]field_new\f[R] arguments are the names of
the fields of type \f[I]POBJ_LIST_ENTRY\f[R] 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[R]() atomically removes
the element \f[I]elm\f[R] from the list referenced by \f[I]head\f[R] and
inserts it into the list referenced by \f[I]head_new\f[R] after the
element \f[I]listelm\f[R].
If \f[I]listelm\f[R] value is \f[I]TOID_NULL\f[R], the object is
inserted at the end of the list.
The \f[I]field\f[R] and \f[I]field_new\f[R] arguments are the names of
the fields of type \f[I]POBJ_LIST_ENTRY\f[R] 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[R]() atomically removes
the element \f[I]elm\f[R] from the list referenced by \f[I]head\f[R] and
inserts it into the list referenced by \f[I]head_new\f[R] before the
element \f[I]listelm\f[R].
If \f[I]listelm\f[R] value is \f[B]TOID_NULL\f[R], the object is
inserted at the head of the list.
The \f[I]field\f[R] and \f[I]field_new\f[R] arguments are the names of
the fields of type \f[I]POBJ_LIST_ENTRY\f[R] in the element structure
that are used to connect the elements in both lists.
.SH SEE ALSO
.PP
\f[B]queue\f[R](3), \f[B]libpmemobj\f[R](7) and
\f[B]<https://pmem.io>\f[R]