libpmemobj(7)

1LIBPMEMOBJ(7)              PMDK Programmer's Manual              LIBPMEMOBJ(7)
2
3
4

NAME

6       libpmemobj - persistent memory transactional object store
7

SYNOPSIS

9              #include <libpmemobj.h>
10              cc -std=gnu99 ... -lpmemobj -lpmem
11
12   Library API versioning:
13              const char *pmemobj_check_version(
14                  unsigned major_required,
15                  unsigned minor_required);
16
17   Managing library behavior:
18              void pmemobj_set_funcs(
19                  void *(*malloc_func)(size_t size),
20                  void (*free_func)(void *ptr),
21                  void *(*realloc_func)(void *ptr, size_t size),
22                  char *(*strdup_func)(const char *s));
23
24   Error handling:
25              const char *pmemobj_errormsg(void);
26
27   Other library functions:
28       A description of other libpmemobj functions can be found on the follow‐
29       ing manual pages:
30
31       • control and statistics: pmemobj_ctl_get(3)
32
33       • create, open, close and validate: pmemobj_open(3)
34
35       • low-level memory manipulation: pmemobj_memcpy_persist(3)
36
37       • locking: pmemobj_mutex_zero(3)
38
39       • persistent object identifier: OID_IS_NULL(3)
40
41       • type-safety: TOID_DECLARE(3)
42
43       • layout declaration: POBJ_LAYOUT_BEGIN(3)
44
45       • non-transactional atomic allocations: pmemobj_alloc(3)
46
47       • root object management: pmemobj_root(3)
48
49       • object containers: pmemobj_first(3)
50
51       • non-transactional  persistent  atomic  circular  doubly-linked  list:
52         pmemobj_list_insert(3), POBJ_LIST_HEAD(3)
53
54       • transactional   object   manipulation:   pmemobj_tx_begin(3),  pmemo‐
55         bj_tx_add_range(3), pmemobj_tx_alloc(3)
56
57       • delayed atomicity actions: pmemobj_action(3) (EXPERIMENTAL)
58

DESCRIPTION

60       libpmemobj provides a transactional object store in  persistent  memory
61       (pmem) for applications that require transactions and persistent memory
62       management using direct access storage (DAX),  which  is  storage  that
63       supports  load/store  access without paging blocks from a block storage
64       device.  Some types of non-volatile memory DIMMs (NVDIMMs) provide this
65       type  of byte addressable access to storage.  A persistent memory aware
66       file system is typically used to expose the direct access  to  applica‐
67       tions.   Memory mapping a file from this type of file system results in
68       load/store, non-paged access to pmem.  libpmemobj builds on  this  type
69       of  memory  mapped  file  using  the low-level pmem support provided by
70       libpmem(7), handling the transactional  updates,  flushing  changes  to
71       persistence, and managing recovery for the application.
72
73       libpmemobj requires the -std=gnu99 compilation flag to build properly.
74
75       libpmemobj is one of a collection of persistent memory libraries avail‐
76       able.  The others are:
77
78       • libpmemblk(7), providing pmem-resident arrays of  fixed-sized  blocks
79         with atomic updates.
80
81       • libpmemlog(7), providing a pmem-resident log file.
82
83       • libpmem(7), low-level persistent memory support.
84
85       Under  normal usage, libpmemobj will never print messages or intention‐
86       ally cause the process to exit.  The only exception to this is the  de‐
87       bugging information, when enabled, as described under DEBUGGING AND ER‐
88       ROR HANDLING, below.
89

LIBRARY API VERSIONING

91       This section describes how the library API is versioned,  allowing  ap‐
92       plications to work with an evolving API.
93
94       The  pmemobj_check_version()  function  is used to see if the installed
95       libpmemobj supports the version of the library API required by  an  ap‐
96       plication.  The easiest way to do this is for the application to supply
97       the compile-time version information, supplied by defines in <libpmemo‐
98       bj.h>, like this:
99
100              reason = pmemobj_check_version(PMEMOBJ_MAJOR_VERSION,
101                                             PMEMOBJ_MINOR_VERSION);
102              if (reason != NULL) {
103                  /* version check failed, reason string tells you why */
104              }
105
106       Any mismatch in the major version number is considered a failure, but a
107       library with a newer minor version number will pass  this  check  since
108       increasing minor versions imply backwards compatibility.
109
110       An  application can also check specifically for the existence of an in‐
111       terface by checking for the version where  that  interface  was  intro‐
112       duced.   These versions are documented in this man page as follows: un‐
113       less otherwise specified, all interfaces described here  are  available
114       in version 1.0 of the library.  Interfaces added after version 1.0 will
115       contain the text introduced in version x.y in the section of this manu‐
116       al describing the feature.
117
118       On  success,  pmemobj_check_version() returns NULL.  Otherwise, the re‐
119       turn value is a static string describing the reason the  version  check
120       failed.   The  string  returned  by pmemobj_check_version() must not be
121       modified or freed.
122

MANAGING LIBRARY BEHAVIOR

124       The pmemobj_set_funcs() function allows an application to override mem‐
125       ory  allocation  calls  used internally by libpmemobj.  Passing in NULL
126       for any of the handlers will cause the libpmemobj default  function  to
127       be  used.   The  library  does  not make heavy use of the system malloc
128       functions, but it does allocate approximately 4-8  kilobytes  for  each
129       memory pool in use.
130
131       By  default, libpmemobj supports up to 1024 parallel transactions/allo‐
132       cations.  For debugging purposes it is possible to decrease this  value
133       by  setting the PMEMOBJ_NLANES environment variable to the desired lim‐
134       it.
135

DEBUGGING AND ERROR HANDLING

137       If an error is detected during the call to a libpmemobj  function,  the
138       application may retrieve an error message describing the reason for the
139       failure from pmemobj_errormsg().  This function returns a pointer to  a
140       static  buffer containing the last error message logged for the current
141       thread.  If errno was set, the error message may include a  description
142       of  the corresponding error code as returned by strerror(3).  The error
143       message buffer is thread-local; errors encountered in one thread do not
144       affect  its value in other threads.  The buffer is never cleared by any
145       library function; its content is significant only when the return value
146       of the immediately preceding call to a libpmemobj function indicated an
147       error, or if errno was set.  The application must not  modify  or  free
148       the error message string, but it may be modified by subsequent calls to
149       other library functions.
150
151       Two versions of libpmemobj are typically  available  on  a  development
152       system.   The  normal  version, accessed when a program is linked using
153       the -lpmemobj option, is optimized for performance.  That version skips
154       checks  that impact performance and never logs any trace information or
155       performs any run-time assertions.
156
157       A second version of libpmemobj, accessed when a program  uses  the  li‐
158       braries  under  /usr/lib/pmdk_debug,  contains  run-time assertions and
159       trace points.  The typical way to access the debug version  is  to  set
160       the  environment  variable  LD_LIBRARY_PATH  to  /usr/lib/pmdk_debug or
161       /usr/lib64/pmdk_debug, as appropriate.  Debugging output is  controlled
162       using the following environment variables.  These variables have no ef‐
163       fect on the non-debug version of the library.
164
165       • PMEMOBJ_LOG_LEVEL
166
167       The value of PMEMOBJ_LOG_LEVEL enables trace points in the  debug  ver‐
168       sion of the library, as follows:
169
170       • 0  - This is the default level when PMEMOBJ_LOG_LEVEL is not set.  No
171         log messages are emitted at this level.
172
173       • 1 - Additional details on any errors detected are logged, in addition
174         to  returning  the errno-based errors as usual.  The same information
175         may be retrieved using pmemobj_errormsg().
176
177       • 2 - A trace of basic operations is logged.
178
179       • 3 - Enables a very verbose amount of function call tracing in the li‐
180         brary.
181
182       • 4 - Enables voluminous and fairly obscure tracing information that is
183         likely only useful to the libpmemobj developers.
184
185       Unless PMEMOBJ_LOG_FILE is set, debugging output is written to stderr.
186
187       • PMEMOBJ_LOG_FILE
188
189       Specifies the name of a file where all logging  information  should  be
190       written.  If the last character in the name is “-”, the PID of the cur‐
191       rent process will be appended to the file name when  the  log  file  is
192       created.   If PMEMOBJ_LOG_FILE is not set, logging output is written to
193       stderr.
194
195       See also libpmem(7) to get information about  other  environment  vari‐
196       ables affecting libpmemobj behavior.
197

EXAMPLE

199       See <https://pmem.io/pmdk/libpmemobj> for examples using the libpmemobj
200       API.
201

ACKNOWLEDGEMENTS

203       libpmemobj builds on the persistent memory programming model recommend‐
204       ed    by    the    SNIA   NVM   Programming   Technical   Work   Group:
205       <https://snia.org/nvmp>
206