.\" Automatically generated by Pandoc 1.16.0.2
.\"
.TH "OID_IS_NULL" "3" "2017-12-22" "PMDK - pmemobj API version 2.2" "PMDK Programmer's Manual"
.hy
.\" Copyright 2014-2017, 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]OID_IS_NULL\f[](), \f[B]OID_EQUALS\f[](),
\f[B]pmemobj_direct\f[](), \f[B]pmemobj_oid\f[](),
\f[B]pmemobj_type_num\f[](), \f[B]pmemobj_pool_by_oid\f[](),
\f[B]pmemobj_pool_by_ptr\f[]() \-\- functions that allow mapping
operations between object addresses, object handles, oids or type
numbers
.SH SYNOPSIS
.IP
.nf
\f[C]
#include\ <libpmemobj.h>
OID_IS_NULL(PMEMoid\ oid)
OID_EQUALS(PMEMoid\ lhs,\ PMEMoid\ rhs)
void\ *pmemobj_direct(PMEMoid\ oid);
PMEMoid\ pmemobj_oid(const\ void\ *addr);\ (EXPERIMENTAL)
uint64_t\ pmemobj_type_num(PMEMoid\ oid);
PMEMobjpool\ *pmemobj_pool_by_oid(PMEMoid\ oid);
PMEMobjpool\ *pmemobj_pool_by_ptr(const\ void\ *addr);
\f[]
.fi
.SH DESCRIPTION
.PP
Each object stored in a persistent memory pool is represented by an
object handle of type \f[I]PMEMoid\f[].
In practice, such a handle is a unique Object IDentifier (\f[I]OID\f[])
of global scope, which means that two objects from different pools will
never have the same \f[I]OID\f[].
The special \f[B]OID_NULL\f[] macro defines a NULL\-like handle that
does not represent any object.
The size of a single object is limited by
\f[B]PMEMOBJ_MAX_ALLOC_SIZE\f[].
Thus an allocation with a requested size greater than this value will
fail.
.PP
An \f[I]OID\f[] cannot be used as a direct pointer to an object.
Each time the program attempts to read or write object data, it must
obtain the current memory address of the object by converting its
\f[I]OID\f[] into a pointer.
.PP
In contrast to the memory address, the \f[I]OID\f[] value for given
object does not change during the life of an object (except for
\f[I]realloc\f[]), and remains valid after closing and reopening the
pool.
For this reason, if an object contains a reference to another persistent
object, for example, to build some kind of a linked data structure, the
reference must be an \f[I]OID\f[] and not a memory address.
.PP
\f[B]pmemobj_direct\f[]() returns a pointer to the \f[I]PMEMoid\f[]
object with handle \f[I]oid\f[].
.PP
\f[B]pmemobj_oid\f[]() returns a \f[I]PMEMoid\f[] handle to the object
pointed to by \f[I]addr\f[].
.PP
\f[B]pmemobj_type_num\f[]() returns the type number of the
\f[I]PMEMoid\f[] object with handle \f[I]oid\f[].
.PP
\f[B]pmemobj_pool_by_oid\f[]() returns a \f[I]PMEMobjpool\f[]* handle to
the pool containing the \f[I]PMEMoid\f[] object with handle
\f[I]oid\f[].
.PP
\f[B]pmemobj_pool_by_ptr\f[]() returns a \f[I]PMEMobjpool\f[]* handle to
the pool containing the address \f[I]addr\f[].
.PP
At the time of allocation (or reallocation), each object may be assigned
a number representing its type.
Such a \f[I]type number\f[] may be used to arrange the persistent
objects based on their actual user\-defined structure type, thus
facilitating implementation of a simple run\-time type safety mechanism.
This also allows iterating through all the objects of a given type that
are stored in the persistent memory pool.
See \f[B]pmemobj_first\f[](3) for more information.
.PP
The \f[B]OID_IS_NULL\f[]() macro checks if \f[I]PMEMoid\f[] represents a
NULL object.
.PP
The \f[B]OID_EQUALS\f[]() macro compares two \f[I]PMEMoid\f[] objects.
.SH RETURN VALUE
.PP
The \f[B]pmemobj_direct\f[]() function returns a pointer to the object
represented by \f[I]oid\f[].
If \f[I]oid\f[] is \f[B]OID_NULL\f[], \f[B]pmemobj_direct\f[]() returns
NULL.
.PP
The \f[B]pmemobj_oid\f[]() function returns a \f[I]PMEMoid\f[] handle to
the object pointed to by \f[I]addr\f[].
If \f[I]addr\f[] is not from within a pmemobj pool, \f[B]OID_NULL\f[] is
returned.
If \f[I]addr\f[] is not the start of an object (does not point to the
beginning of a valid allocation), the resulting \f[I]PMEMoid\f[] can be
safely used only with:
.IP \[bu] 2
\f[B]pmemobj_pool_by_oid\f[]()
.IP \[bu] 2
\f[B]pmemobj_direct\f[]()
.IP \[bu] 2
\f[B]pmemobj_tx_add_range\f[](3)
.PP
The \f[B]pmemobj_type_num\f[]() function returns the type number of the
object represented by \f[I]oid\f[].
.PP
The \f[B]pmemobj_pool_by_oid\f[]() function returns a handle to the pool
that contains the object represented by \f[I]oid\f[].
If the the pool is not open or \f[I]oid\f[] is \f[B]OID_NULL\f[],
\f[B]pmemobj_pool_by_oid\f[]() returns NULL.
.PP
The \f[B]pmemobj_pool_by_ptr\f[]() function returns a handle to the pool
that contains the address, or NULL if the address does not belong to any
open pool.
.SH NOTES
.PP
For performance reasons, on Linux and FreeBSD the
\f[B]pmemobj_direct\f[]() function is inlined by default.
To use the non\-inlined variant of \f[B]pmemobj_direct\f[](), define
\f[B]PMEMOBJ_DIRECT_NON_INLINE\f[] prior to the \f[I]#include\f[] of
\f[B]<libpmemobj.h>\f[], either with \f[I]#define\f[] or with the
\f[I]\-D\f[] option to the compiler.
.SH SEE ALSO
.PP
\f[B]libpmemobj\f[](7) and \f[B]<http://pmem.io>\f[]