.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "" "" "2023-05-26" "PMDK - " "PMDK Programmer's Manual"
.hy
.\" SPDX-License-Identifier: BSD-3-Clause
.\" Copyright 2017-2018, Intel Corporation
.SH NAME
.PP
\f[B]pmemobj_first\f[R](), \f[B]pmemobj_next\f[R](),
\f[B]POBJ_FIRST\f[R](), \f[B]POBJ_FIRST_TYPE_NUM\f[R](),
\f[B]POBJ_NEXT\f[R](), \f[B]POBJ_NEXT_TYPE_NUM\f[R](),
\f[B]POBJ_FOREACH\f[R](), \f[B]POBJ_FOREACH_SAFE\f[R](),
\f[B]POBJ_FOREACH_TYPE\f[R](), \f[B]POBJ_FOREACH_SAFE_TYPE\f[R]() -
pmemobj container operations
.SH SYNOPSIS
.IP
.nf
\f[C]
#include <libpmemobj.h>

PMEMoid pmemobj_first(PMEMobjpool *pop);
PMEMoid pmemobj_next(PMEMoid oid);

POBJ_FIRST(PMEMobjpool *pop, TYPE)
POBJ_FIRST_TYPE_NUM(PMEMobjpool *pop, uint64_t type_num)
POBJ_NEXT(TOID oid)
POBJ_NEXT_TYPE_NUM(PMEMoid oid)

POBJ_FOREACH(PMEMobjpool *pop, PMEMoid varoid)
POBJ_FOREACH_SAFE(PMEMobjpool *pop, PMEMoid varoid, PMEMoid nvaroid)
POBJ_FOREACH_TYPE(PMEMobjpool *pop, TOID var)
POBJ_FOREACH_SAFE_TYPE(PMEMobjpool *pop, TOID var, TOID nvar)
\f[R]
.fi
.SH DESCRIPTION
.PP
The \f[B]libpmemobj\f[R](7) container operations provide a mechanism
that allows iteration through the internal object collection, either
looking for a specific object, or performing a specific operation on
each object of a given type.
Software should not make any assumptions about the order of the objects
in the internal object containers.
.PP
The \f[B]pmemobj_first\f[R]() function returns the first object from the
pool.
.PP
The \f[B]POBJ_FIRST\f[R]() macro returns the first object from the pool
of the type specified by \f[I]TYPE\f[R].
.PP
The \f[B]POBJ_FIRST_TYPE_NUM\f[R]() macro returns the first object from
the pool of the type specified by \f[I]type_num\f[R].
.PP
The \f[B]pmemobj_next\f[R]() function returns the next object from the
pool.
.PP
The \f[B]POBJ_NEXT\f[R]() macro returns the next object of the same type
as the object referenced by \f[I]oid\f[R].
.PP
The \f[B]POBJ_NEXT_TYPE_NUM\f[R]() macro returns the next object of the
same type number as the object referenced by \f[I]oid\f[R].
.PP
The following four macros provide a more convenient way to iterate
through the internal collections, performing a specific operation on
each object.
.PP
The \f[B]POBJ_FOREACH\f[R]() macro performs a specific operation on each
allocated object stored in the persistent memory pool \f[I]pop\f[R].
It traverses the internal collection of all the objects, assigning a
handle to each element in turn to \f[I]varoid\f[R].
.PP
The \f[B]POBJ_FOREACH_TYPE\f[R]() macro performs a specific operation on
each allocated object stored in the persistent memory pool \f[I]pop\f[R]
that has the same type as \f[I]var\f[R].
It traverses the internal collection of all the objects of the specified
type, assigning a handle to each element in turn to \f[I]var\f[R].
.PP
The macros \f[B]POBJ_FOREACH_SAFE\f[R]() and
\f[B]POBJ_FOREACH_SAFE_TYPE\f[R]() work in a similar fashion as
\f[B]POBJ_FOREACH\f[R]() and \f[B]POBJ_FOREACH_TYPE\f[R](), except that
prior to performing the operation on the object, they preserve a handle
to the next object in the collection by assigning it to
\f[I]nvaroid\f[R] or \f[I]nvar\f[R], respectively.
This allows safe deletion of selected objects while iterating through
the collection.
.SH RETURN VALUE
.PP
\f[B]pmemobj_first\f[R]() returns the first object from the pool, or, if
the pool is empty, \f[B]OID_NULL\f[R].
.PP
\f[B]pmemobj_next\f[R]() returns the next object from the pool.
If the object referenced by \f[I]oid\f[R] is the last object in the
collection, or if \f[I]oid\f[R] is \f[I]OID_NULL\f[R],
\f[B]pmemobj_next\f[R]() returns \f[B]OID_NULL\f[R].
.SH SEE ALSO
.PP
\f[B]libpmemobj\f[R](7) and \f[B]<https://pmem.io>\f[R]