1LIBPMEMCTO(7) PMDK Programmer's Manual LIBPMEMCTO(7)
2
6 libpmemcto -- close-to-open persistence
7
9 #include <libpmemcto.h>
10 cc ... -lpmemcto -lpmem
11 Library API versioning:
13 const char *pmemcto_check_version(
14 unsigned major_required,
15 unsigned minor_required);
16 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 Error handling:
26 const char *pmemcto_errormsg(void);
27 Other library functions:
29 A description of other libpmemcto functions can be found on the follow‐
30 ing manual pages:
31 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
37 libpmemcto is a persistent memory allocator with no overhead imposed by
38 run-time flushing or transactional updates:
39 · It runs at traditional volatile memory allocator speeds - there is no
41 flushing or consistency check at run-time.
42 · An overhead imposed only when program exits normally and have to
44 flush the file.
45 · The program flushes the pool contents when it exits, and then re‐
47 builds the pool on the next run.
48 · 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 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 · libpmemobj(7), a general use persistent memory API, providing memory
66 allocation and transactional operations on variable-sized objects.
67 · libpmemblk(7), providing pmem-resident arrays of fixed-sized blocks
69 with atomic updates.
70 · libpmemlog(7), providing a pmem-resident log file.
72 · libpmem(7), low-level persistent memory support.
74 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 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 This library builds on the low-level pmem support provided by libp‐
89 mem(7).
90 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
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
111 This section describes how the library API is versioned, allowing ap‐
112 plications to work with an evolving API.
113 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 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 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 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 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
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
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 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 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 · PMEMCTO_LOG_LEVEL
181 The value of PMEMCTO_LOG_LEVEL enables trace points in the debug ver‐
183 sion of the library, as follows:
184 · 0 - This is the default level when PMEMCTO_LOG_LEVEL is not set. No
186 log messages are emitted at this level.
187 · 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 · 2 - A trace of basic operations is logged.
193 · 3 - Enables a very verbose amount of function call tracing in the li‐
195 brary.
196 · 4 - Enables voluminous and fairly obscure tracing information that is
198 likely only useful to the libpmemcto developers.
199 Unless PMEMCTO_LOG_FILE is set, debugging output is written to stderr.
201 · PMEMCTO_LOG_FILE
203 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 See also libpmem(7) for information on other environment variables that
211 may affect libpmemcto behavior.
212
214 The following example creates a memory pool, allocates some memory to
215 contain the string "hello, world", and then frees that memory.
216 #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 /* size of the pmemcto pool -- 1 GB */
226 #define POOL_SIZE ((size_t)(1 << 30))
227 /* name of our layout in the pool */
229 #define LAYOUT_NAME "example_layout"
230 struct root {
232 char *str;
233 char *data;
234 };
235 int
237 main(int argc, char *argv[])
238 {
239 const char path[] = "/pmem-fs/myfile";
240 PMEMctopool *pcp;
241 /* create the pmemcto pool or open it if already exists */
243 pcp = pmemcto_create(path, LAYOUT_NAME, POOL_SIZE, 0666);
244 if (pcp == NULL)
246 pcp = pmemcto_open(path, LAYOUT_NAME);
247 if (pcp == NULL) {
249 perror(path);
250 exit(1);
251 }
252 /* get the root object pointer */
254 struct root *rootp = pmemcto_get_root_pointer(pcp);
255 if (rootp == NULL) {
257 /* allocate root object */
258 rootp = pmemcto_malloc(pcp, sizeof(*rootp));
259 if (rootp == NULL) {
261 perror(pmemcto_errormsg());
262 exit(1);
263 }
264 /* save the root object pointer */
266 pmemcto_set_root_pointer(pcp, rootp);
267 rootp->str = pmemcto_strdup(pcp, "Hello World!");
269 rootp->data = NULL;
270 }
271 /* ... */
273 pmemcto_close(pcp);
275 }
276 See <http://pmem.io/pmdk/libpmemcto> for more examples using the libp‐
278 memcto API.
279
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
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
290 libpmemcto is part of the PMDK since version 1.4 and is available from
291 <https://github.com/pmem/pmdk>
292
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 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
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>
309PMDK - libpmemcto API version 1.0 2018-03-13 LIBPMEMCTO(7)