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