1RPMEM_CREATE(3) PMDK Programmer's Manual RPMEM_CREATE(3)
2
6 rpmem_create()(DEPRECATED), rpmem_open()(DEPRECATED), rpmem_set_at‐
7 tr()(DEPRECATED), rpmem_close()(DEPRECATED), rpmem_remove()(DEPRECAT‐
8 ED), - most commonly used functions for remote access to persistent
9 memory
10
12 #include <librpmem.h>
13 RPMEMpool *rpmem_create(const char *target, const char *pool_set_name,
15 void *pool_addr, size_t pool_size, unsigned *nlanes,
16 const struct rpmem_pool_attr *create_attr);
17 RPMEMpool *rpmem_open(const char *target, const char *pool_set_name,
18 void *pool_addr, size_t pool_size, unsigned *nlanes,
19 struct rpmem_pool_attr *open_attr);
20 int rpmem_set_attr(RPMEMpool *rpp, const struct rpmem_pool_attr *attr);
21 int rpmem_close(RPMEMpool *rpp);
22 int rpmem_remove(const char *target, const char *pool_set_name, int flags);
23
25 The rpmem_create() function creates a remote pool on a given target
26 node, using pool set file pool_set_name to map the remote pool.
27 pool_set_name is a relative path in the root config directory on the
28 target node. For pool set file format and options see poolset(5).
29 pool_addr is a pointer to the associated local memory pool with size
30 pool_size. Both pool_addr and pool_size must be aligned to the sys‐
31 tem's page size (see sysconf(3)). The size of the remote pool must be
32 at least pool_size. See REMOTE POOL SIZE, below, for details. nlanes
33 points to the maximum number of lanes which the caller is requesting.
34 Upon successful creation of the remote pool, *nlanes is set to the max‐
35 imum number of lanes supported by both the local and remote nodes. See
36 LANES, below, for details. The create_attr structure contains the at‐
37 tributes used for creating the remote pool. If the create_attr struc‐
38 ture is not NULL, a pool with internal metadata is created. The meta‐
39 data is stored in the first 4096 bytes of the pool and can be read when
40 opening the remote pool with rpmem_open(). To prevent user from over‐
41 writing the pool metadata, this region is not accessible to the user
42 via rpmem_persist(). If create_attr is NULL or zeroed, remote pool set
43 file must contain the NOHDRS option. In that case the remote pool is
44 created without internal metadata in it and the entire pool space is
45 available to the user. See rpmem_persist(3) for details.
46 The rpmem_open() function opens the existing remote pool with set file
48 pool_set_name on remote node target. pool_set_name is a relative path
49 in the root config directory on the target node. pool_addr is a point‐
50 er to the associated local memory pool of size pool_size. Both
51 pool_addr and pool_size must be aligned to the system's page size (see
52 sysconf(3)). The size of the remote pool must be at least pool_size.
53 See REMOTE POOL SIZE, below, for details. nlanes points to the maximum
54 number of lanes which the caller is requesting. Upon successful open‐
55 ing of the remote pool, *nlanes is set to the maximum number of lanes
56 supported by both the local and remote nodes. See LANES, below, for
57 details.
58 The rpmem_set_attr() function overwrites the pool's attributes. The
60 attr structure contains the attributes used for overwriting the remote
61 pool attributes that were passed to rpmem_create() at pool creation.
62 If attr is NULL, a zeroed structure with attributes will be used. New
63 attributes are stored in the pool's metadata.
64 The rpmem_close() function closes the remote pool rpp. All resources
66 are released on both the local and remote nodes. The remote pool it‐
67 self persists on the remote node and may be re-opened at a later time
68 using rpmem_open().
69 The rpmem_remove() function removes the remote pool with set file name
71 pool_set_name from node target. The pool_set_name is a relative path
72 in the root config directory on the target node. By default only the
73 pool part files are removed; the pool set file is left untouched. If
74 the pool is not consistent, the rpmem_remove() function fails. The
75 flags argument determines the behavior of rpmem_remove(). flags may be
76 either 0 or the bitwise OR of one or more of the following flags:
77 • RPMEM_REMOVE_FORCE - Ignore errors when opening an inconsistent pool.
79 The pool set file must still be in appropriate format for the pool to
80 be removed.
81 • RPMEM_REMOVE_POOL_SET - Remove the pool set file after removing the
83 pool described by this pool set.
84
86 On success, rpmem_create() returns an opaque handle to the remote pool
87 for use in subsequent librpmem calls. If any error prevents the remote
88 pool from being created, rpmem_create() returns NULL and sets errno ap‐
89 propriately.
90 On success, rpmem_open() returns an opaque handle to the remote pool
92 for subsequent librpmem calls. If the open_attr argument is not NULL,
93 the remote pool attributes are returned in the provided structure. If
94 the remote pool was created without internal metadata, zeroes are re‐
95 turned in the open_attr structure on successful call to rpmem_open().
96 If any error prevents the remote pool from being opened, rpmem_open()
97 returns NULL and sets errno appropriately.
98 On success, rpmem_set_attr() returns 0. On error, it returns -1 and
100 sets errno appropriately.
101 On success, rpmem_close() returns 0. On error, it returns a non-zero
103 value and sets errno appropriately.
104 On success, rpmem_remove() returns 0. On error, it returns a non-zero
106 value and sets errno appropriately.
107
109 REMOTE POOL SIZE
110 The size of a remote pool depends on the configuration in the pool set
111 file on the remote node (see poolset(5)). If no pool set options is
112 used in the remote pool set file, the remote pool size is the sum of
113 the sizes of all part files, decreased by 4096 bytes per part file.
114 4096 bytes of each part file are utilized for storing internal metada‐
115 ta. If the SINGLEHDR option is used in the remote pool set file, the
116 remote pool size is the sum of sizes of all part files, decreased once
117 by 4096 bytes. In this case only the first part contains internal
118 metadata. If a remote pool set file contains the NOHDRS option, the
119 remote pool size is the sum of sizes of all its part files. In this
120 case none of the parts contains internal metadata. For other conse‐
121 quences of using the SINGLEHDR and NOHDRS options see rpmem_persist(3).
122 RPMEM_MIN_PART and RPMEM_MIN_POOL in <librpmem.h> define the minimum
123 size allowed by librpmem for a part file and a remote pool, respective‐
124 ly.
125 LANES
127 The term lane means an isolated path of execution. The underlying
128 hardware utilized by both local and remote nodes may have limited re‐
129 sources that restrict the maximum number of parallel rpmem_persist(3)
130 operations. The maximum number of supported lanes is returned by the
131 rpmem_open() and rpmem_create() function calls. The caller passes the
132 maximum number of lanes requested in *nlanes. If the pool is success‐
133 fully created or opened, *nlanes is updated to reflect the minimum of
134 the number of lanes requested by the caller and the maximum number of
135 lanes supported by underlying hardware. The application is obligated
136 to use at most the returned number of lanes in parallel.
137 rpmem_persist(3) does not provide any locking mechanism; thus any seri‐
139 alization of calls must be performed by the application if required.
140 Each lane requires a separate connection, represented by a file de‐
142 scriptor. If the system runs out of free file descriptors during rp‐
143 mem_create() or rpmem_open(), these functions will fail. See nofile in
144 limits.conf(5) for more details.
145
147 rpmem_persist(3), sysconf(3), limits.conf(5), libpmemobj(7), librp‐
148 mem(7) and <https://pmem.io>
149PMDK - rpmem API version 1.3 2022-05-24 RPMEM_CREATE(3)