.\" Automatically generated by Pandoc 2.0.6
.\"
.TH "RPMEM_PERSIST" "3" "2022-08-25" "PMDK - rpmem API version 1.3" "PMDK Programmer's Manual"
.hy
.\" SPDX-License-Identifier: BSD-3-Clause
.\" Copyright 2017-2022, Intel Corporation
.SH NAME
.PP
\f[B]rpmem_persist\f[]()(DEPRECATED),
\f[B]rpmem_deep_persist\f[]()(DEPRECATED),
\f[B]rpmem_flush\f[]()(DEPRECATED), \f[B]rpmem_drain\f[]()(DEPRECATED),
\f[B]rpmem_read\f[]()(DEPRECATED) \- functions to copy and read remote
pools
.SH SYNOPSIS
.IP
.nf
\f[C]
#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);
\f[]
.fi
.SH DESCRIPTION
.PP
The \f[B]rpmem_persist\f[]() function copies data of given
\f[I]length\f[] at given \f[I]offset\f[] 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 \f[I]rpp\f[] handle which must be
returned from either \f[B]rpmem_open\f[](3) or \f[B]rpmem_create\f[](3).
The \f[I]offset\f[] is relative to the \f[I]pool_addr\f[] specified in
the \f[B]rpmem_open\f[](3) or \f[B]rpmem_create\f[](3) call.
If the remote pool was created using \f[B]rpmem_create\f[]() with
non\-NULL \f[I]create_attr\f[] argument, \f[I]offset\f[] 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 \f[I]create_attr\f[] argument, the
pool metadata is not stored with the pool and \f[I]offset\f[] can be any
nonnegative number.
The \f[I]offset\f[] and \f[I]length\f[] combined must not exceed the
\f[I]pool_size\f[] passed to \f[B]rpmem_open\f[](3) or
\f[B]rpmem_create\f[](3).
The \f[B]rpmem_persist\f[]() operation is performed using the given
\f[I]lane\f[] number.
The lane must be less than the value returned by \f[B]rpmem_open\f[](3)
or \f[B]rpmem_create\f[](3) through the \f[I]nlanes\f[] argument (so it
can take a value from 0 to \f[I]nlanes\f[] \- 1).
The \f[I]flags\f[] argument can be 0 or RPMEM_PERSIST_RELAXED which
means the persist operation will be done without any guarantees
regarding atomicity of memory transfer.
.PP
The \f[B]rpmem_deep_persist\f[]() function works in the same way as
\f[B]rpmem_persist\f[](3) function, but additionally it flushes the data
to the lowest possible persistency domain available from software.
Please see \f[B]pmem_deep_persist\f[](3) for details.
.PP
The \f[B]rpmem_flush\f[]() and \f[B]rpmem_drain\f[]() functions are two
halves of the single \f[B]rpmem_persist\f[]().
The \f[B]rpmem_persist\f[]() copies data and makes it persistent in the
one shot, where \f[B]rpmem_flush\f[]() and \f[B]rpmem_drain\f[]() split
this operation into two stages.
The \f[B]rpmem_flush\f[]() copies data of given \f[I]length\f[] at a
given \f[I]offset\f[] from the associated local memory pool to the
remote node.
The \f[B]rpmem_drain\f[]() makes sure the data copied in all preceding
\f[B]rpmem_flush\f[]() calls is persistent on the remote node before the
function returns.
Data copied using \f[B]rpmem_flush\f[]() can not be considered
persistent on the remote node before return from following
\f[B]rpmem_drain\f[]().
Single \f[B]rpmem_drain\f[]() confirms persistence on the remote node of
data copied by all \f[B]rpmem_flush\f[]() functions called before it and
using the same \f[I]lane\f[].
The last \f[B]rpmem_flush\f[]() + \f[B]rpmem_drain\f[]() can be replaced
with \f[B]rpmem_persist\f[]() at no cost.
.PP
The \f[I]flags\f[] argument for \f[B]rpmem_flush\f[]() can be 0 or
RPMEM_FLUSH_RELAXED which means the flush operation will be done without
any guarantees regarding atomicity of memory transfer.
The \f[I]flags\f[] argument for \f[B]rpmem_drain\f[]() must be 0.
.PP
The \f[B]rpmem_flush\f[]() function performance is affected by
\f[B]RPMEM_WORK_QUEUE_SIZE\f[] environment variable (see
\f[B]librpmem\f[](7) for more details).
.PP
The \f[B]rpmem_read\f[]() function reads \f[I]length\f[] bytes of data
from a remote pool at \f[I]offset\f[] and copies it to the buffer
\f[I]buff\f[].
The operation is performed on the specified \f[I]lane\f[].
The lane must be less than the value returned by \f[B]rpmem_open\f[](3)
or \f[B]rpmem_create\f[](3) through the \f[I]nlanes\f[] argument (so it
can take a value from 0 to \f[I]nlanes\f[] \- 1).
The \f[I]rpp\f[] must point to a remote pool opened or created
previously by \f[B]rpmem_open\f[](3) or \f[B]rpmem_create\f[](3).
.SH RETURN VALUE
.PP
The \f[B]rpmem_persist\f[]() function returns 0 if the entire memory
area was made persistent on the remote node.
Otherwise it returns a non\-zero value and sets \f[I]errno\f[]
appropriately.
.PP
The \f[B]rpmem_flush\f[]() 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 \f[I]errno\f[]
appropriately.
.PP
The \f[B]rpmem_drain\f[]() function returns 0 if the memory areas
duplicated by all \f[B]rpmem_flush\f[]() calls preceding the
\f[B]rpmem_drain\f[]() are made persistent on the remote node.
Otherwise, it returns a non\-zero value and sets \f[I]errno\f[]
appropriately.
.PP
The \f[B]rpmem_read\f[]() function returns 0 if the data was read
entirely.
Otherwise it returns a non\-zero value and sets \f[I]errno\f[]
appropriately.
.SH CAVEATS
.PP
Ordering of \f[B]rpmem_flush\f[]() and \f[B]rpmem_persist\f[]()
operations which are using different \f[I]lane\f[] values is not
guaranteed.
.SH SEE ALSO
.PP
\f[B]rpmem_create\f[](3), \f[B]rpmem_open\f[](3),
\f[B]rpmem_persist\f[](3), \f[B]sysconf\f[](3), \f[B]limits.conf\f[](5),
\f[B]libpmemobj\f[](7) and \f[B]<https://pmem.io>\f[]