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

NAME

6       libpmemcto -- close-to-open persistence
7

SYNOPSIS

9              #include <libpmemcto.h>
10              cc ... -lpmemcto -lpmem
11
12   Library API versioning:
13              const char *pmemcto_check_version(
14                  unsigned major_required,
15                  unsigned minor_required);
16
17   Managing library behavior:
18              void pmemcto_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                  void (*print_func)(const char *s));
24
25   Error handling:
26              const char *pmemcto_errormsg(void);
27
28   Other library functions:
29       A description of other libpmemcto functions can be found on the follow‐
30       ing manual pages:
31
32       pmemcto_aligned_alloc(3),     pmemcto_malloc(3),     pmemcto_malloc_us‐
33       able_size(3),   pmemcto_open(3),   pmemcto_set_root_pointer(3),  pmemc‐
34       to_stats_print(3), pmemcto_strdup(3), pmemcto_wcsdup(3)
35

DESCRIPTION

37       libpmemcto is a persistent memory allocator with no overhead imposed by
38       run-time flushing or transactional updates:
39
40       · It runs at traditional volatile memory allocator speeds - there is no
41         flushing or consistency check at run-time.
42
43       · An overhead imposed only when program  exits  normally  and  have  to
44         flush the file.
45
46       · The  program  flushes  the  pool contents when it exits, and then re‐
47         builds the pool on the next run.
48
49       · If the program crashes before  flushing  the  file  (or  if  flushing
50         fails),  the pool is in an inconsistent state causing subsequent pool
51         opening to fail.
52
53       libpmemcto provides common malloc-like interfaces to persistent  memory
54       pools built on memory-mapped files.  libpmemcto uses the mmap(2) system
55       call to create a pool of persistent memory.  The  library  is  intended
56       for applications using Direct Access storage (DAX), which is memory-ad‐
57       dressable persistent storage that supports  load/store  access  without
58       being  paged via the system page cache.  A Persistent Memory-aware file
59       system is typically used to provide this type of  access.   Memory-map‐
60       ping a file from a Persistent Memory-aware file system provides the raw
61       memory pools, and this library supplies the more  familiar  malloc-like
62       interfaces on top of those pools.  libpmemcto is one of a collection of
63       persistent memory libraries available, the others are:
64
65       · libpmemobj(7), a general use persistent memory API, providing  memory
66         allocation and transactional operations on variable-sized objects.
67
68       · libpmemblk(7),  providing  pmem-resident arrays of fixed-sized blocks
69         with atomic updates.
70
71       · libpmemlog(7), providing a pmem-resident log file.
72
73       · libpmem(7), low-level persistent memory support.
74
75       Under normal usage, libpmemcto will never print messages or  intention‐
76       ally  cause  the process to exit.  Exceptions to this are prints caused
77       by calls to pmemcto_stats_print(3), or by  enabling  debugging  as  de‐
78       scribed  under  DEBUGGING  AND  ERROR HANDLING below.  The library uses
79       pthreads(7) to be fully MT-safe, but never creates or destroys  threads
80       itself.   The library does not make use of any signals, networking, and
81       never calls select() or poll().
82
83       The system memory allocation routines like malloc() and free() are used
84       by libpmemcto for managing a small amount of run-time state, but appli‐
85       cations are allowed to override these calls if  necessary  (see  pmemc‐
86       to_set_funcs()).
87
88       This  library  builds  on  the low-level pmem support provided by libp‐
89       mem(7).
90
91       To use close-to-open persistence supplied by libpmemcto, a memory  pool
92       is first created using the pmemcto_create() function described in pmem‐
93       cto_open(3).  The other libpmemcto functions operate on  the  resulting
94       block  memory  pool using the opaque handle, of type PMEMctopool*, that
95       is returned by pmemcto_create() or pmemcto_open().   Internally,  libp‐
96       memcto  will  use  either  pmem_persist(3) or msync(2) when it needs to
97       flush changes, depending on whether the memory pool appears to be  per‐
98       sistent  memory  or a regular file (see the pmem_is_pmem(3) function in
99       libpmem(7) for more information).  There is no need for applications to
100       flush  changes directly when using the close-to-open persistence memory
101       API provided by libpmemcto.
102

CAVEATS

104       libpmemcto relies on the library destructor being called from the  main
105       thread.   For this reason, all functions that might trigger destruction
106       (e.g.  dlclose(3)) should be called in the main thread.  Otherwise some
107       of  the  resources  associated with that thread might not be cleaned up
108       properly.
109

LIBRARY API VERSIONING

111       This section describes how the library API is versioned,  allowing  ap‐
112       plications to work with an evolving API.
113
114       The  pmemcto_check_version()  function is used to determine whether the
115       installed libpmemcto supports the version of the library  API  required
116       by  an  application.  The easiest way to do this is for the application
117       to supply the compile-time version information, supplied by defines  in
118       <ibpmemcto.h>, like this:
119
120              reason = pmemcto_check_version(PMEMCTO_MAJOR_VERSION,
121                                             PMEMCTO_MINOR_VERSION);
122              if (reason != NULL) {
123                  /* version check failed, reason string tells you why */
124              }
125
126       Any mismatch in the major version number is considered a failure, but a
127       library with a newer minor version number will pass  this  check  since
128       increasing minor versions imply backwards compatibility.
129
130       An  application can also check specifically for the existence of an in‐
131       terface by checking for the version where  that  interface  was  intro‐
132       duced.   These versions are documented in this man page as follows: un‐
133       less otherwise specified, all interfaces described here  are  available
134       in version 1.0 of the library.  Interfaces added after version 1.0 will
135       contain the text introduced in version x.y in the section of this manu‐
136       al describing the feature.
137
138       When the version check performed by pmemcto_check_version() is success‐
139       ful, the return value is NULL.  Otherwise the return value is a  static
140       string describing the reason for failing the version check.  The string
141       returned by pmemcto_check_version() must not be modified or freed.
142

MANAGING LIBRARY BEHAVIOR

144       The pmemcto_set_funcs() function allows an application to override mem‐
145       ory  allocation  calls  used internally by libpmemcto.  Passing in NULL
146       for any of the handlers will cause the libpmemcto default  function  to
147       be  used.   The  library  does  not make heavy use of the system malloc
148       functions, but it does allocate approximately 4-8  kilobytes  for  each
149       memory pool in use.
150

DEBUGGING AND ERROR HANDLING

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

EXAMPLE

214       The following example creates a memory pool, allocates some  memory  to
215       contain the string "hello, world", and then frees that memory.
216
217              #include <stdio.h>
218              #include <fcntl.h>
219              #include <errno.h>
220              #include <stdlib.h>
221              #include <unistd.h>
222              #include <string.h>
223              #include <libpmemcto.h>
224
225              /* size of the pmemcto pool -- 1 GB */
226              #define POOL_SIZE ((size_t)(1 << 30))
227
228              /* name of our layout in the pool */
229              #define LAYOUT_NAME "example_layout"
230
231              struct root {
232                  char *str;
233                  char *data;
234              };
235
236              int
237              main(int argc, char *argv[])
238              {
239                  const char path[] = "/pmem-fs/myfile";
240                  PMEMctopool *pcp;
241
242                  /* create the pmemcto pool or open it if already exists */
243                  pcp = pmemcto_create(path, LAYOUT_NAME, POOL_SIZE, 0666);
244
245                  if (pcp == NULL)
246                      pcp = pmemcto_open(path, LAYOUT_NAME);
247
248                  if (pcp == NULL) {
249                      perror(path);
250                      exit(1);
251                  }
252
253                  /* get the root object pointer */
254                  struct root *rootp = pmemcto_get_root_pointer(pcp);
255
256                  if (rootp == NULL) {
257                      /* allocate root object */
258                      rootp = pmemcto_malloc(pcp, sizeof(*rootp));
259
260                      if (rootp == NULL) {
261                          perror(pmemcto_errormsg());
262                          exit(1);
263                      }
264
265                      /* save the root object pointer */
266                      pmemcto_set_root_pointer(pcp, rootp);
267
268                      rootp->str = pmemcto_strdup(pcp, "Hello World!");
269                      rootp->data = NULL;
270                  }
271
272                  /* ... */
273
274                  pmemcto_close(pcp);
275              }
276
277       See  <http://pmem.io/pmdk/libpmemcto> for more examples using the libp‐
278       memcto API.
279

BUGS

281       Unlike libpmemobj(3), data replication is not supported in  libpmemcto.
282       Thus, it is not allowed to specify replica sections in pool set files.
283

NOTES

285       Unlike the normal malloc(), which asks the system for additional memory
286       when it runs out, libpmemcto allocates the size it is told to and never
287       attempts to grow or shrink that memory pool.
288

AVAILABILITY

290       libpmemcto  is part of the PMDK since version 1.4 and is available from
291       <https://github.com/pmem/pmdk>
292

ACKNOWLEDGEMENTS

294       libpmemcto depends on jemalloc, written by Jason Evans, to do the heavy
295       lifting of managing dynamic memory allocation.  See: <http://www.canon
296       ware.com/jemalloc>
297
298       libpmemcto builds on the persistent memory programming model recommend‐
299       ed    by    the    SNIA   NVM   Programming   Technical   Work   Group:
300       <http://snia.org/nvmp>
301

SEE ALSO

303       ndctl-create-namespace(1), dlclose(2), mmap(2), jemalloc(3), malloc(3),
304       pmemcto_aligned_alloc(3), pmemcto_errormsg(3), pmemcto_malloc(3), pmem‐
305       cto_malloc_usable_size(3),   pmemcto_open(3),   pmemcto_set_root_point‐
306       er(3),  pmemcto_stats_print(3),  pmemcto_strdup(3),  pmemcto_wcsdup(3),
307       libpmem(7),    libpmemblk(7),    libpmemlog(7),    libpmemobj(7)    and
308       <http://pmem.io>
309
310
311
312PMDK - libpmemcto API version 1.0 2018-03-13                     LIBPMEMCTO(7)
Impressum