libpmemobj(7)

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

NAME

6       libpmemobj - persistent memory transactional object store
7
8              NOTE:  Support  for  Windows  and  FreeBSD deprecated since PMDK
9              1.13.0 release and will be removed in the PMDK 1.14.0 release.
10

SYNOPSIS

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

DESCRIPTION

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

LIBRARY API VERSIONING

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

MANAGING LIBRARY BEHAVIOR

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

DEBUGGING AND ERROR HANDLING

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

EXAMPLE

202       See <https://pmem.io/pmdk/libpmemobj> for examples using the libpmemobj
203       API.
204

ACKNOWLEDGEMENTS

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