pmemobj_direct(3)

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

NAME

6       OID_IS_NULL(),  OID_EQUALS(),  pmemobj_direct(),  pmemobj_oid(), pmemo‐
7       bj_type_num(), pmemobj_pool_by_oid(),  pmemobj_pool_by_ptr()  --  func‐
8       tions  that  allow  mapping operations between object addresses, object
9       handles, oids or type numbers
10

SYNOPSIS

12              #include <libpmemobj.h>
13
14              OID_IS_NULL(PMEMoid oid)
15              OID_EQUALS(PMEMoid lhs, PMEMoid rhs)
16
17              void *pmemobj_direct(PMEMoid oid);
18              PMEMoid pmemobj_oid(const void *addr);
19              uint64_t pmemobj_type_num(PMEMoid oid);
20              PMEMobjpool *pmemobj_pool_by_oid(PMEMoid oid);
21              PMEMobjpool *pmemobj_pool_by_ptr(const void *addr);
22

DESCRIPTION

24       Each object stored in a persistent memory pool is represented by an ob‐
25       ject  handle  of  type PMEMoid.  In practice, such a handle is a unique
26       Object IDentifier (OID) of global scope, which means that  two  objects
27       from  different  pools  will  never  have  the  same  OID.  The special
28       OID_NULL macro defines a NULL-like handle that does not  represent  any
29       object.   The  size  of  a  single object is limited by PMEMOBJ_MAX_AL‐
30       LOC_SIZE.  Thus an allocation with a requested size greater  than  this
31       value will fail.
32
33       An  OID cannot be used as a direct pointer to an object.  Each time the
34       program attempts to read or write object data, it must obtain the  cur‐
35       rent memory address of the object by converting its OID into a pointer.
36
37       In  contrast to the memory address, the OID value for given object does
38       not change during the life of an object (except for realloc),  and  re‐
39       mains  valid after closing and reopening the pool.  For this reason, if
40       an object contains a reference to another persistent object, for  exam‐
41       ple,  to build some kind of a linked data structure, the reference must
42       be an OID and not a memory address.
43
44       pmemobj_direct() returns a pointer to the PMEMoid  object  with  handle
45       oid.
46
47       pmemobj_oid()  returns a PMEMoid handle to the object pointed to by ad‐
48       dr.
49
50       pmemobj_type_num() returns the type number of the PMEMoid  object  with
51       handle oid.
52
53       pmemobj_pool_by_oid()  returns  a  PMEMobjpool* handle to the pool con‐
54       taining the PMEMoid object with handle oid.
55
56       pmemobj_pool_by_ptr() returns a PMEMobjpool* handle to  the  pool  con‐
57       taining the address addr.
58
59       At  the  time  of  allocation (or reallocation), each object may be as‐
60       signed a number representing its type.  Such a type number may be  used
61       to  arrange  the  persistent objects based on their actual user-defined
62       structure type, thus facilitating implementation of a  simple  run-time
63       type  safety mechanism.  This also allows iterating through all the ob‐
64       jects of a given type that are stored in the  persistent  memory  pool.
65       See pmemobj_first(3) for more information.
66
67       The OID_IS_NULL() macro checks if PMEMoid represents a NULL object.
68
69       The OID_EQUALS() macro compares two PMEMoid objects.
70

RETURN VALUE

72       The  pmemobj_direct()  function  returns a pointer to the object repre‐
73       sented by oid.  If oid is OID_NULL, pmemobj_direct() returns NULL.
74
75       The pmemobj_oid() function returns  a  PMEMoid  handle  to  the  object
76       pointed  to  by  addr.   If  addr  is  not  from within a pmemobj pool,
77       OID_NULL is returned.  If addr is not the start of an object (does  not
78       point  to  the  beginning of a valid allocation), the resulting PMEMoid
79       can be safely used only with:
80
81       · pmemobj_pool_by_oid()
82
83       · pmemobj_direct()
84
85       · pmemobj_tx_add_range(3)
86
87       The pmemobj_type_num() function returns the type number of  the  object
88       represented by oid.
89
90       The  pmemobj_pool_by_oid()  function  returns a handle to the pool that
91       contains the object represented by oid.  If the the pool is not open or
92       oid is OID_NULL, pmemobj_pool_by_oid() returns NULL.
93
94       The  pmemobj_pool_by_ptr()  function  returns a handle to the pool that
95       contains the address, or NULL if the address does  not  belong  to  any
96       open pool.
97

NOTES

99       For  performance  reasons,  on  Linux  and FreeBSD the pmemobj_direct()
100       function is inlined by default.  To  use  the  non-inlined  variant  of
101       pmemobj_direct(),  define  PMEMOBJ_DIRECT_NON_INLINE  prior to the #in‐
102       clude of <libpmemobj.h>, either with #define or with the -D  option  to
103       the compiler.
104

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

SEE ALSO