Ubuntu Manpage: rpmem_create(), rpmem_open(), rpmem_set_attr(), rpmem_close(), rpmem_remove()

Provided by: librpmem-dev_1.4.1-0ubuntu1~18.04.1_amd64

NAME

       rpmem_create(),  rpmem_open(),  rpmem_set_attr(),  rpmem_close(),  rpmem_remove()  -  most
       commonly used functions for remote access to persistent memory

SYNOPSIS

              #include <librpmem.h>

              RPMEMpool *rpmem_create(const char *target, const char *pool_set_name,
                  void *pool_addr, size_t pool_size, unsigned *nlanes,
                  const struct rpmem_pool_attr *create_attr);
              RPMEMpool *rpmem_open(const char *target, const char *pool_set_name,
                  void *pool_addr, size_t pool_size, unsigned *nlanes,
                  struct rpmem_pool_attr *open_attr);
              int rpmem_set_attr(RPMEMpool *rpp, const struct rpmem_pool_attr *attr);
              int rpmem_close(RPMEMpool *rpp);
              int rpmem_remove(const char *target, const char *pool_set_name, int flags);

DESCRIPTION

       The rpmem_create() function creates a remote pool on a given target node, using  pool  set
       file  pool_set_name  to map the remote pool.  pool_set_name is a relative path in the root
       config directory on the target node.  For pool set file format and options see poolset(5).
       pool_addr  is  a  pointer  to  the associated local memory pool with size pool_size.  Both
       pool_addr and pool_size must be aligned to the system's page size (see  sysconf(3)).   The
       size  of  the  remote  pool  must be at least pool_size.  See REMOTE POOL SIZE, below, for
       details.  nlanes points to the maximum number of lanes which  the  caller  is  requesting.
       Upon successful creation of the remote pool, *nlanes is set to the maximum number of lanes
       supported by both the local and  remote  nodes.   See  LANES,  below,  for  details.   The
       create_attr  structure  contains the attributes used for creating the remote pool.  If the
       create_attr structure is not NULL, a pool with internal metadata is created.  The metadata
       is stored in the first 4096 bytes of the pool and can be read when opening the remote pool
       with rpmem_open().  To prevent user from overwriting the pool metadata, this region is not
       accessible to the user via rpmem_persist().  If create_attr is NULL or zeroed, remote pool
       set file must contain the NOHDRS option.  In that case the remote pool is created  without
       internal  metadata  in  it  and  the  entire  pool  space  is  available to the user.  See
       rpmem_persist(3) for details.

       The rpmem_open() function opens the existing remote pool with set  file  pool_set_name  on
       remote  node target.  pool_set_name is a relative path in the root config directory on the
       target node.  pool_addr is  a  pointer  to  the  associated  local  memory  pool  of  size
       pool_size.   Both  pool_addr  and pool_size must be aligned to the system's page size (see
       sysconf(3)).  The size of the remote pool must be at least  pool_size.   See  REMOTE  POOL
       SIZE,  below,  for details.  nlanes points to the maximum number of lanes which the caller
       is requesting.  Upon successful opening of the remote pool, *nlanes is set to the  maximum
       number  of  lanes  supported  by  both  the local and remote nodes.  See LANES, below, for
       details.

       The rpmem_set_attr() function  overwrites  the  pool's  attributes.   The  attr  structure
       contains  the  attributes used for overwriting the remote pool attributes that were passed
       to rpmem_create() at pool creation.  If attr is NULL, a zeroed structure  with  attributes
       will be used.  New attributes are stored in the pool's metadata.

       The rpmem_close() function closes the remote pool rpp.  All resources are released on both
       the local and remote nodes.  The remote pool itself persists on the remote node and may be
       re-opened at a later time using rpmem_open().

       The  rpmem_remove() function removes the remote pool with set file name pool_set_name from
       node target.  The pool_set_name is a relative path in the root  config  directory  on  the
       target  node.   By default only the pool part files are removed; the pool set file is left
       untouched.  If the pool is not consistent, the rpmem_remove() function fails.   The  flags
       argument  determines the behavior of rpmem_remove().  flags may be either 0 or the bitwise
       OR of one or more of the following flags:

       • RPMEM_REMOVE_FORCE - Ignore errors when opening an inconsistent pool.  The pool set file
         must still be in appropriate format for the pool to be removed.

       • RPMEM_REMOVE_POOL_SET  -  Remove  the pool set file after removing the pool described by
         this pool set.

RETURN VALUE

       On success, rpmem_create() returns an  opaque  handle  to  the  remote  pool  for  use  in
       subsequent  librpmem  calls.   If  any  error prevents the remote pool from being created,
       rpmem_create() returns NULL and sets errno appropriately.

       On success, rpmem_open() returns an opaque  handle  to  the  remote  pool  for  subsequent
       librpmem  calls.   If  the  open_attr argument is not NULL, the remote pool attributes are
       returned in the provided structure.  If the  remote  pool  was  created  without  internal
       metadata,   zeroes  are  returned  in  the  open_attr  structure  on  successful  call  to
       rpmem_open().  If any error prevents the  remote  pool  from  being  opened,  rpmem_open()
       returns NULL and sets errno appropriately.

       On  success,  rpmem_set_attr()  returns  0.   On  error,  it  returns  -1  and  sets errno
       appropriately.

       On success, rpmem_close() returns 0.  On error, it returns a non-zero value and sets errno
       appropriately.

       On  success,  rpmem_remove()  returns  0.   On error, it returns a non-zero value and sets
       errno appropriately.

NOTES

REMOTE POOL SIZE
The size of a remote pool depends on the configuration in the pool set file on the remote
node (see poolset(5)). If no pool set options is used in the remote pool set file, the
remote pool size is the sum of the sizes of all part files, decreased by 4096 bytes per
part file. 4096 bytes of each part file are utilized for storing internal metadata. If
the SINGLEHDR option is used in the remote pool set file, the remote pool size is the sum
of sizes of all part files, decreased once by 4096 bytes. In this case only the first
part contains internal metadata. If a remote pool set file contains the NOHDRS option,
the remote pool size is the sum of sizes of all its part files. In this case none of the
parts contains internal metadata. For other consequences of using the SINGLEHDR and
NOHDRS options see rpmem_persist(3). RPMEM_MIN_PART and RPMEM_MIN_POOL in <librpmem.h>
define the minimum size allowed by librpmem for a part file and a remote pool,
respectively.

LANES
The term lane means an isolated path of execution. The underlying hardware utilized by
both local and remote nodes may have limited resources that restrict the maximum number of
parallel rpmem_persist(3) operations. The maximum number of supported lanes is returned
by the rpmem_open() and rpmem_create() function calls. The caller passes the maximum
number of lanes requested in *nlanes. If the pool is successfully created or opened,
*nlanes is updated to reflect the minimum of the number of lanes requested by the caller
and the maximum number of lanes supported by underlying hardware. The application is
obligated to use at most the returned number of lanes in parallel.

rpmem_persist(3) does not provide any locking mechanism; thus any serialization of calls
must be performed by the application if required.

Each lane requires a separate connection, represented by a file descriptor. If the system
runs out of free file descriptors during rpmem_create() or rpmem_open(), these functions
will fail. See nofile in limits.conf(5) for more details.

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

SEE ALSO