.\" Automatically generated by Pandoc 2.0.6
.\"
.TH "TOID_DECLARE" "3" "2022-08-25" "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]TOID_DECLARE\f[](), \f[B]TOID_DECLARE_ROOT\f[](), \f[B]TOID\f[](),
\f[B]TOID_TYPE_NUM\f[](), \f[B]TOID_TYPE_NUM_OF\f[](),
\f[B]TOID_VALID\f[](), \f[B]OID_INSTANCEOF\f[](),
\f[B]TOID_ASSIGN\f[](), \f[B]TOID_IS_NULL\f[](), \f[B]TOID_EQUALS\f[](),
\f[B]TOID_TYPEOF\f[](), \f[B]TOID_OFFSETOF\f[](), \f[B]DIRECT_RW\f[](),
\f[B]D_RW\f[](), \f[B]DIRECT_RO\f[](), \f[B]D_RO\f[]() \- 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[]
.fi
.SH DESCRIPTION
.PP
Operating on untyped object handles, as well as on direct untyped object
pointers (\f[I]void*\f[]), may be confusing and error\-prone.
To facilitate type safety, \f[B]libpmemobj\f[](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[]() macro declares a typed \f[I]OID\f[] of
user\-defined type \f[I]TYPE\f[] and type number \f[I]type_num\f[].
.PP
The \f[B]TOID_DECLARE_ROOT\f[]() macro declares a typed \f[I]OID\f[] of
user\-defined type \f[I]ROOT_TYPE\f[] and root object type number
\f[B]POBJ_ROOT_TYPE_NUM\f[].
.PP
The \f[B]TOID\f[]() macro declares a handle to an object of type
\f[I]TYPE\f[], where \f[I]TYPE\f[] is the name of a user\-defined
structure.
The typed \f[I]OID\f[] must be declared first using the
\f[B]TOID_DECLARE\f[](), \f[B]TOID_DECLARE_ROOT\f[](),
\f[B]POBJ_LAYOUT_TOID\f[](3) or \f[B]POBJ_LAYOUT_ROOT\f[](3) macros.
.PP
The \f[B]TOID_TYPE_NUM\f[]() macro returns the type number of the type
specified by \f[I]TYPE\f[].
.PP
The \f[B]TOID_TYPE_NUM_OF\f[]() macro returns the type number of the
object specified by \f[I]oid\f[].
The type number is read from the typed \f[I]OID\f[].
.PP
The \f[B]TOID_VALID\f[]() macro validates whether the type number stored
in the object's metadata is equal to the type number read from the typed
\f[I]OID\f[].
.PP
The \f[B]OID_INSTANCEOF\f[]() macro checks whether the \f[I]oid\f[] is
of type \f[I]TYPE\f[].
.PP
The \f[B]TOID_ASSIGN\f[]() macro assigns the object handle
\f[I]VALUE\f[] to typed \f[I]OID\f[] \f[I]o\f[].
.PP
The \f[B]TOID_IS_NULL\f[]() macro evaluates to true if the object handle
represented by \f[I]o\f[] is \f[B]OID_NULL\f[].
.PP
The \f[B]TOID_EQUALS\f[]() macro evaluates to true if both the
\f[I]lhs\f[] and \f[I]rhs\f[] object handles reference the same
persistent object.
.PP
The \f[B]TOID_TYPEOF\f[]() macro returns the type of the object handle
represented by typed \f[I]OID\f[] \f[I]o\f[].
.PP
The \f[B]TOID_OFFSETOF\f[]() macro returns the offset of the
\f[I]FIELD\f[] member from the start of the object represented by
\f[I]o\f[].
.PP
The \f[B]DIRECT_RW\f[]() macro and its shortened form \f[B]D_RW\f[]()
return a typed write pointer (\f[I]TYPE*\f[]) to an object represented
by \f[I]oid\f[].
If \f[I]oid\f[] is \f[B]OID_NULL\f[], the macro evaluates to NULL.
.PP
The \f[B]DIRECT_RO\f[]() macro and its shortened form \f[B]D_RO\f[]()
return a typed read\-only (const) pointer (\f[I]TYPE*\f[]) to an object
represented by \f[I]oid\f[].
If \f[I]oid\f[] is \f[B]OID_NULL\f[], the macro evaluates to NULL.
.SH SEE ALSO
.PP
\f[B]OID_IS_NULL\f[](3), \f[B]POBJ_LAYOUT_ROOT\f[](3),
\f[B]POBJ_LAYOUT_TOID\f[](3), \f[B]libpmemobj\f[](7) and
\f[B]<https://pmem.io>\f[]