.\" Automatically generated by Pandoc 2.10.1
.\"
.TH "OID_IS_NULL" "3" "2020-10-28" "PMDK - pmemobj API version 2.3" "PMDK Programmer's Manual"
.hy
.\" SPDX-License-Identifier: BSD-3-Clause
.\" Copyright 2017-2018, Intel Corporation
.SH NAME
.PP
\f[B]OID_IS_NULL\f[R](), \f[B]OID_EQUALS\f[R](),
\f[B]pmemobj_direct\f[R](), \f[B]pmemobj_oid\f[R](),
\f[B]pmemobj_type_num\f[R](), \f[B]pmemobj_pool_by_oid\f[R](),
\f[B]pmemobj_pool_by_ptr\f[R]() - 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);
uint64_t pmemobj_type_num(PMEMoid oid);
PMEMobjpool *pmemobj_pool_by_oid(PMEMoid oid);
PMEMobjpool *pmemobj_pool_by_ptr(const void *addr);
void *pmemobj_volatile(PMEMobjpool *pop, struct pmemvlt *vlt,
    size_t size, void *ptr,
    int (*constr)(void *ptr, void *arg), void *arg); (EXPERIMENTAL)
\f[R]
.fi
.SH DESCRIPTION
.PP
Each object stored in a persistent memory pool is represented by an
object handle of type \f[I]PMEMoid\f[R].
In practice, such a handle is a unique Object IDentifier (\f[I]OID\f[R])
of global scope, which means that two objects from different pools will
never have the same \f[I]OID\f[R].
The special \f[B]OID_NULL\f[R] 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[R].
Thus an allocation with a requested size greater than this value will
fail.
.PP
An \f[I]OID\f[R] 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[R] into a pointer.
.PP
In contrast to the memory address, the \f[I]OID\f[R] value for given
object does not change during the life of an object (except for
\f[I]realloc\f[R]), 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[R] and not a memory address.
.PP
\f[B]pmemobj_direct\f[R]() returns a pointer to the \f[I]PMEMoid\f[R]
object with handle \f[I]oid\f[R].
.PP
\f[B]pmemobj_oid\f[R]() returns a \f[I]PMEMoid\f[R] handle to the object
pointed to by \f[I]addr\f[R].
.PP
\f[B]pmemobj_type_num\f[R]() returns the type number of the
\f[I]PMEMoid\f[R] object with handle \f[I]oid\f[R].
.PP
\f[B]pmemobj_pool_by_oid\f[R]() returns a \f[I]PMEMobjpool\f[R]* handle
to the pool containing the \f[I]PMEMoid\f[R] object with handle
\f[I]oid\f[R].
.PP
\f[B]pmemobj_pool_by_ptr\f[R]() returns a \f[I]PMEMobjpool\f[R]* handle
to the pool containing the address \f[I]addr\f[R].
.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[R] 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[R](3) for more information.
.PP
The \f[B]OID_IS_NULL\f[R]() macro checks if \f[I]PMEMoid\f[R] represents
a NULL object.
.PP
The \f[B]OID_EQUALS\f[R]() macro compares two \f[I]PMEMoid\f[R] objects.
.PP
For special cases where volatile (transient) variables need to be stored
on persistent memory, there\[cq]s a mechanism composed of \f[I]struct
pmemvlt\f[R] type and \f[B]pmemobj_volatile()\f[R] function.
To use it, the \f[I]struct pmemvlt\f[R] needs to be placed in the
neighborhood of transient data region.
The \f[I]PMEMvlt\f[R] macro can be used to construct such a region.
The \f[I]struct pmemvlt\f[R] must be zeroed prior to use.
This can be easily done in object constructor or in a transaction
directly after an allocation.
When the \f[B]pmemobj_volatile()\f[R] function is called on a
\f[I]struct pmemvlt\f[R], it will return the pointer to the data and it
will ensure that the provided constructor function is called exactly
once in the current instance of the pmemobj pool.
The constructor is called with the \f[I]ptr\f[R] pointer to the data,
and this function will return the same pointer if the constructor
returns \f[I]0\f[R], otherwise NULL is returned.
The \f[I]size\f[R] argument must accurately describe the total size of
the volatile memory region that will be accessed.
Calling \f[B]pmemobj_volatile()\f[R] on the same region with different
sizes is undefined behavior.
For this mechanism to be effective, all accesses to transient variables
must go through it, otherwise there\[cq]s a risk of the constructor not
being called on the first load.
Maintaining transient state on persistent memory is challenging due to
difficulties with dynamic resources acquisition and subsequent resource
release.
For example, one needs to consider what happens with volatile state of
an object which is being freed inside of a transaction, especially with
regards to the possibility of an abort.
It\[cq]s generally recommended to entirely separate the persistent and
transient states, and when it\[cq]s not possible, to only store types
which do not require lifecycle management (i.e., primitive types) inside
of volatile regions.
.SH RETURN VALUE
.PP
The \f[B]pmemobj_direct\f[R]() function returns a pointer to the object
represented by \f[I]oid\f[R].
If \f[I]oid\f[R] is \f[B]OID_NULL\f[R], \f[B]pmemobj_direct\f[R]()
returns NULL.
.PP
The \f[B]pmemobj_oid\f[R]() function returns a \f[I]PMEMoid\f[R] handle
to the object pointed to by \f[I]addr\f[R].
If \f[I]addr\f[R] is not from within a pmemobj pool, \f[B]OID_NULL\f[R]
is returned.
If \f[I]addr\f[R] is not the start of an object (does not point to the
beginning of a valid allocation), the resulting \f[I]PMEMoid\f[R] can be
safely used only with:
.IP \[bu] 2
\f[B]pmemobj_pool_by_oid\f[R]()
.IP \[bu] 2
\f[B]pmemobj_direct\f[R]()
.IP \[bu] 2
\f[B]pmemobj_tx_add_range\f[R](3)
.PP
The \f[B]pmemobj_type_num\f[R]() function returns the type number of the
object represented by \f[I]oid\f[R].
.PP
The \f[B]pmemobj_pool_by_oid\f[R]() function returns a handle to the
pool that contains the object represented by \f[I]oid\f[R].
If the pool is not open or \f[I]oid\f[R] is \f[B]OID_NULL\f[R],
\f[B]pmemobj_pool_by_oid\f[R]() returns NULL.
.PP
The \f[B]pmemobj_pool_by_ptr\f[R]() 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[R]() function is inlined by default.
To use the non-inlined variant of \f[B]pmemobj_direct\f[R](), define
\f[B]PMEMOBJ_DIRECT_NON_INLINE\f[R] prior to the \f[I]#include\f[R] of
\f[B]<libpmemobj.h>\f[R], either with \f[I]#define\f[R] or with the
\f[I]-D\f[R] option to the compiler.
.SH EXAMPLES
.PP
The following code shows how to store transient variables on persistent
memory.
.IP
.nf
\f[C]
struct my_data {
    PMEMvlt(uint64_t) foo;
    uint64_t bar;
};

int
my_data_constructor(void *ptr, void *arg)
{
    uint64_t *foo = ptr;
    *foo = 0;

    return 0;
}

PMEMobjpool *pop = ...;

struct my_data *data = D_RW(...);

uint64_t *foo = pmemobj_volatile(pop, &data->foo.vlt, &data->foo.value,
    my_data_constructor, NULL);

assert(*foo == 0);
\f[R]
.fi
.SH SEE ALSO
.PP
\f[B]libpmemobj\f[R](7) and \f[B]<https://pmem.io>\f[R]