.\" 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]TOID_DECLARE\f[R](), \f[B]TOID_DECLARE_ROOT\f[R](),
\f[B]TOID\f[R](), \f[B]TOID_TYPE_NUM\f[R](),
\f[B]TOID_TYPE_NUM_OF\f[R](), \f[B]TOID_VALID\f[R](),
\f[B]OID_INSTANCEOF\f[R](), \f[B]TOID_ASSIGN\f[R](),
\f[B]TOID_IS_NULL\f[R](), \f[B]TOID_EQUALS\f[R](),
\f[B]TOID_TYPEOF\f[R](), \f[B]TOID_OFFSETOF\f[R](),
\f[B]DIRECT_RW\f[R](), \f[B]D_RW\f[R](), \f[B]DIRECT_RO\f[R](),
\f[B]D_RO\f[R]() - libpmemobj type safety mechanism
.SH SYNOPSIS
.IP
.nf
\f[C]
#include <libpmemobj.h>

TOID_DECLARE(TYPE, uint64_t type_num)
TOID_DECLARE_ROOT(ROOT_TYPE)
TOID(TYPE)
TOID_TYPE_NUM(TYPE)
TOID_TYPE_NUM_OF(TOID oid)
TOID_VALID(TOID oid)
OID_INSTANCEOF(PMEMoid oid, TYPE)
TOID_ASSIGN(TOID o, VALUE)
TOID_IS_NULL(TOID o)
TOID_EQUALS(TOID lhs, TOID rhs)
TOID_TYPEOF(TOID o)
TOID_OFFSETOF(TOID o, FILED)
DIRECT_RW(TOID oid)
D_RW(TOID oid)
DIRECT_RO(TOID oid)
D_RO(TOID oid)
\f[R]
.fi
.SH DESCRIPTION
.PP
Operating on untyped object handles, as well as on direct untyped object
pointers (\f[I]void*\f[R]), may be confusing and error-prone.
To facilitate type safety, \f[B]libpmemobj\f[R](7) defines a set of
macros that provide static type enforcement, catching potential errors
at compile time.
For example, a compile-time error is generated when an attempt is made
to assign a handle to an object of one type to the object handle
variable of another type of object.
.PP
The \f[B]TOID_DECLARE\f[R]() macro declares a typed \f[I]OID\f[R] of
user-defined type \f[I]TYPE\f[R] and type number \f[I]type_num\f[R].
.PP
The \f[B]TOID_DECLARE_ROOT\f[R]() macro declares a typed \f[I]OID\f[R]
of user-defined type \f[I]ROOT_TYPE\f[R] and root object type number
\f[B]POBJ_ROOT_TYPE_NUM\f[R].
.PP
The \f[B]TOID\f[R]() macro declares a handle to an object of type
\f[I]TYPE\f[R], where \f[I]TYPE\f[R] is the name of a user-defined
structure.
The typed \f[I]OID\f[R] must be declared first using the
\f[B]TOID_DECLARE\f[R](), \f[B]TOID_DECLARE_ROOT\f[R](),
\f[B]POBJ_LAYOUT_TOID\f[R](3) or \f[B]POBJ_LAYOUT_ROOT\f[R](3) macros.
.PP
The \f[B]TOID_TYPE_NUM\f[R]() macro returns the type number of the type
specified by \f[I]TYPE\f[R].
.PP
The \f[B]TOID_TYPE_NUM_OF\f[R]() macro returns the type number of the
object specified by \f[I]oid\f[R].
The type number is read from the typed \f[I]OID\f[R].
.PP
The \f[B]TOID_VALID\f[R]() macro validates whether the type number
stored in the object\[cq]s metadata is equal to the type number read
from the typed \f[I]OID\f[R].
.PP
The \f[B]OID_INSTANCEOF\f[R]() macro checks whether the \f[I]oid\f[R] is
of type \f[I]TYPE\f[R].
.PP
The \f[B]TOID_ASSIGN\f[R]() macro assigns the object handle
\f[I]VALUE\f[R] to typed \f[I]OID\f[R] \f[I]o\f[R].
.PP
The \f[B]TOID_IS_NULL\f[R]() macro evaluates to true if the object
handle represented by \f[I]o\f[R] is \f[B]OID_NULL\f[R].
.PP
The \f[B]TOID_EQUALS\f[R]() macro evaluates to true if both the
\f[I]lhs\f[R] and \f[I]rhs\f[R] object handles reference the same
persistent object.
.PP
The \f[B]TOID_TYPEOF\f[R]() macro returns the type of the object handle
represented by typed \f[I]OID\f[R] \f[I]o\f[R].
.PP
The \f[B]TOID_OFFSETOF\f[R]() macro returns the offset of the
\f[I]FIELD\f[R] member from the start of the object represented by
\f[I]o\f[R].
.PP
The \f[B]DIRECT_RW\f[R]() macro and its shortened form \f[B]D_RW\f[R]()
return a typed write pointer (\f[I]TYPE*\f[R]) to an object represented
by \f[I]oid\f[R].
If \f[I]oid\f[R] is \f[B]OID_NULL\f[R], the macro evaluates to NULL.
.PP
The \f[B]DIRECT_RO\f[R]() macro and its shortened form \f[B]D_RO\f[R]()
return a typed read-only (const) pointer (\f[I]TYPE*\f[R]) to an object
represented by \f[I]oid\f[R].
If \f[I]oid\f[R] is \f[B]OID_NULL\f[R], the macro evaluates to NULL.
.SH SEE ALSO
.PP
\f[B]OID_IS_NULL\f[R](3), \f[B]POBJ_LAYOUT_ROOT\f[R](3),
\f[B]POBJ_LAYOUT_TOID\f[R](3), \f[B]libpmemobj\f[R](7) and
\f[B]<https://pmem.io>\f[R]