1TOID_DECLARE(3)            PMDK Programmer's Manual            TOID_DECLARE(3)
2
3
4

NAME

6       TOID_DECLARE(),     TOID_DECLARE_ROOT(),    TOID(),    TOID_TYPE_NUM(),
7       TOID_TYPE_NUM_OF(),  TOID_VALID(),   OID_INSTANCEOF(),   TOID_ASSIGN(),
8       TOID_IS_NULL(),   TOID_EQUALS(),  TOID_TYPEOF(),  TOID_OFFSETOF(),  DI‐
9       RECT_RW(), D_RW(), DIRECT_RO(), D_RO() - libpmemobj type safety  mecha‐
10       nism
11

SYNOPSIS

13              #include <libpmemobj.h>
14
15              TOID_DECLARE(TYPE, uint64_t type_num)
16              TOID_DECLARE_ROOT(ROOT_TYPE)
17              TOID(TYPE)
18              TOID_TYPE_NUM(TYPE)
19              TOID_TYPE_NUM_OF(TOID oid)
20              TOID_VALID(TOID oid)
21              OID_INSTANCEOF(PMEMoid oid, TYPE)
22              TOID_ASSIGN(TOID o, VALUE)
23              TOID_IS_NULL(TOID o)
24              TOID_EQUALS(TOID lhs, TOID rhs)
25              TOID_TYPEOF(TOID o)
26              TOID_OFFSETOF(TOID o, FILED)
27              DIRECT_RW(TOID oid)
28              D_RW(TOID oid)
29              DIRECT_RO(TOID oid)
30              D_RO(TOID oid)
31

DESCRIPTION

33       Operating  on  untyped object handles, as well as on direct untyped ob‐
34       ject pointers (void*), may be confusing and error-prone.  To facilitate
35       type  safety, libpmemobj(7) defines a set of macros that provide static
36       type enforcement, catching potential errors at compile time.  For exam‐
37       ple,  a  compile-time error is generated when an attempt is made to as‐
38       sign a handle to an object of one type to the object handle variable of
39       another type of object.
40
41       The TOID_DECLARE() macro declares a typed OID of user-defined type TYPE
42       and type number type_num.
43
44       The TOID_DECLARE_ROOT() macro declares a typed OID of user-defined type
45       ROOT_TYPE and root object type number POBJ_ROOT_TYPE_NUM.
46
47       The  TOID()  macro  declares  a handle to an object of type TYPE, where
48       TYPE is the name of a user-defined structure.  The typed  OID  must  be
49       declared first using the TOID_DECLARE(), TOID_DECLARE_ROOT(), POBJ_LAY‐
50       OUT_TOID(3) or POBJ_LAYOUT_ROOT(3) macros.
51
52       The TOID_TYPE_NUM() macro returns the type number of the type specified
53       by TYPE.
54
55       The  TOID_TYPE_NUM_OF()  macro  returns  the  type number of the object
56       specified by oid.  The type number is read from the typed OID.
57
58       The TOID_VALID() macro validates whether the type number stored in  the
59       object's metadata is equal to the type number read from the typed OID.
60
61       The OID_INSTANCEOF() macro checks whether the oid is of type TYPE.
62
63       The TOID_ASSIGN() macro assigns the object handle VALUE to typed OID o.
64
65       The  TOID_IS_NULL() macro evaluates to true if the object handle repre‐
66       sented by o is OID_NULL.
67
68       The TOID_EQUALS() macro evaluates to true if both the lhs and  rhs  ob‐
69       ject handles reference the same persistent object.
70
71       The  TOID_TYPEOF()  macro  returns the type of the object handle repre‐
72       sented by typed OID o.
73
74       The TOID_OFFSETOF() macro returns the offset of the FIELD  member  from
75       the start of the object represented by o.
76
77       The  DIRECT_RW()  macro  and  its  shortened form D_RW() return a typed
78       write pointer (TYPE*) to an object  represented  by  oid.   If  oid  is
79       OID_NULL, the macro evaluates to NULL.
80
81       The  DIRECT_RO()  macro  and  its  shortened form D_RO() return a typed
82       read-only (const) pointer (TYPE*) to an object represented by oid.   If
83       oid is OID_NULL, the macro evaluates to NULL.
84

SEE ALSO

86       OID_IS_NULL(3), POBJ_LAYOUT_ROOT(3), POBJ_LAYOUT_TOID(3), libpmemobj(7)
87       and <https://pmem.io>
88
89
90
91PMDK - pmemobj API version 2.3    2022-05-24                   TOID_DECLARE(3)
Impressum