1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
.\" Automatically generated by Pandoc 2.1.3
.\"
.TH "TOID_DECLARE" "3" "2018-07-18" "PMDK - pmemobj API version 2.3" "PMDK Programmer's Manual"
.hy
.\" Copyright 2014-2018, 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]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]<http://pmem.io>\f[]
|
