NAME

       rpmem_persist(), rpmem_deep_persist(), rpmem_flush(), rpmem_drain(), rpmem_read() - functions to copy and
       read remote pools

SYNOPSIS

              #include <librpmem.h>

              int rpmem_persist(RPMEMpool *rpp, size_t offset,
                  size_t length, unsigned lane, unsigned flags);
              int rpmem_deep_persist(RPMEMpool *rpp, size_t offset,
                  size_t length, unsigned lane);

              int rpmem_flush(RPMEMpool *rpp, size_t offset,
                  size_t length, unsigned lane, unsigned flags);
              int rpmem_drain(RPMEMpool *rpp, unsigned lane, unsigned flags);

              int rpmem_read(RPMEMpool *rpp, void *buff, size_t offset,
                  size_t length, unsigned lane);

DESCRIPTION

       The rpmem_persist() function copies data of given length at given offset from the associated local memory
       pool  and  makes  sure the data is persistent on the remote node before the function returns.  The remote
       node is identified by the rpp handle which must be returned from either rpmem_open(3) or rpmem_create(3).
       The  offset  is relative to the pool_addr specified in the rpmem_open(3) or rpmem_create(3) call.  If the
       remote pool was created using rpmem_create() with non-NULL create_attr argument, offset has to be greater
       or  equal  to  4096.  In that case the first 4096 bytes of the pool is used for storing the pool metadata
       and cannot be overwritten.  If the pool was created with NULL create_attr argument, the pool metadata  is
       not  stored  with the pool and offset can be any nonnegative number.  The offset and length combined must
       not exceed the pool_size passed to rpmem_open(3) or rpmem_create(3).  The  rpmem_persist()  operation  is
       performed using the given lane number.  The lane must be less than the value returned by rpmem_open(3) or
       rpmem_create(3) through the nlanes argument (so it can take a value from 0 to nlanes  -  1).   The  flags
       argument  can  be  0  or RPMEM_PERSIST_RELAXED which means the persist operation will be done without any
       guarantees regarding atomicity of memory transfer.

       The rpmem_deep_persist() function works in the same way as rpmem_persist(3) function, but additionally it
       flushes  the  data  to  the  lowest  possible  persistency  domain  available  from software.  Please see
       pmem_deep_persist(3) for details.

       The rpmem_flush() and rpmem_drain()  functions  are  two  halves  of  the  single  rpmem_persist().   The
       rpmem_persist()  copies  data  and  makes  it  persistent  in  the  one  shot,  where  rpmem_flush()  and
       rpmem_drain() split this operation into two stages.  The rpmem_flush() copies data of given length  at  a
       given  offset from the associated local memory pool to the remote node.  The rpmem_drain() makes sure the
       data copied in all preceding rpmem_flush() calls is persistent on the remote  node  before  the  function
       returns.   Data  copied  using  rpmem_flush()  can not be considered persistent on the remote node before
       return from following rpmem_drain().  Single rpmem_drain() confirms persistence on  the  remote  node  of
       data  copied  by  all  rpmem_flush()  functions  called  before  it  and  using  the same lane.  The last
       rpmem_flush() + rpmem_drain() can be replaced with rpmem_persist() at no cost.

       The flags argument for rpmem_flush() can be 0 or RPMEM_FLUSH_RELAXED which means the flush operation will
       be  done  without  any  guarantees  regarding  atomicity  of  memory  transfer.   The  flags argument for
       rpmem_drain() must be 0.

       The rpmem_flush() function performance is affected by  RPMEM_WORK_QUEUE_SIZE  environment  variable  (see
       librpmem(7) for more details).

       The  rpmem_read()  function  reads length bytes of data from a remote pool at offset and copies it to the
       buffer buff.  The operation is performed on the specified lane.  The lane must be  less  than  the  value
       returned  by  rpmem_open(3) or rpmem_create(3) through the nlanes argument (so it can take a value from 0
       to nlanes - 1).  The rpp must point to a remote pool opened or created  previously  by  rpmem_open(3)  or
       rpmem_create(3).

RETURN VALUE

       The  rpmem_persist() function returns 0 if the entire memory area was made persistent on the remote node.
       Otherwise it returns a non-zero value and sets errno appropriately.

       The rpmem_flush() function returns 0 if duplication of the memory area to the remote node was initialized
       successfully.  Otherwise, it returns a non-zero value and sets errno appropriately.

       The  rpmem_drain() function returns 0 if the memory areas duplicated by all rpmem_flush() calls preceding
       the rpmem_drain() are made persistent on the remote node.  Otherwise, it returns  a  non-zero  value  and
       sets errno appropriately.

       The rpmem_read() function returns 0 if the data was read entirely.  Otherwise it returns a non-zero value
       and sets errno appropriately.

CAVEATS

       Ordering of rpmem_flush() and rpmem_persist() operations which are using different  lane  values  is  not
       guaranteed.

SEE ALSO

       rpmem_create(3),   rpmem_open(3),   rpmem_persist(3),   sysconf(3),   limits.conf(5),  libpmemobj(7)  and
       <https://pmem.io>