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

NAME

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

SYNOPSIS

11              #include <librpmem.h>
12
13              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

DESCRIPTION

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
46       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
58       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
64       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
69       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
77RPMEM_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
81RPMEM_REMOVE_POOL_SET - Remove the pool set file after  removing  the
82         pool described by this pool set.
83

RETURN VALUE

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
90       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
98       On success, rpmem_set_attr() returns 0.  On error, it  returns  -1  and
99       sets errno appropriately.
100
101       On  success,  rpmem_close() returns 0.  On error, it returns a non-zero
102       value and sets errno appropriately.
103
104       On success, rpmem_remove() returns 0.  On error, it returns a  non-zero
105       value and sets errno appropriately.
106

NOTES

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
125   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
137       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
140       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

SEE ALSO

146       rpmem_persist(3),  sysconf(3),  limits.conf(5),  libpmemobj(7),  librp‐
147       mem(7) and <https://pmem.io>
148
149
150
151PMDK - rpmem API version 1.3      2021-01-26                   RPMEM_CREATE(3)
Impressum