rpmem_persist(3)

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

NAME

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

SYNOPSIS

10              #include <librpmem.h>
11
12              int rpmem_persist(RPMEMpool *rpp, size_t offset,
13                  size_t length, unsigned lane, unsigned flags);
14              int rpmem_deep_persist(RPMEMpool *rpp, size_t offset,
15                  size_t length, unsigned lane);
16
17              int rpmem_flush(RPMEMpool *rpp, size_t offset,
18                  size_t length, unsigned lane, unsigned flags);
19              int rpmem_drain(RPMEMpool *rpp, unsigned lane, unsigned flags);
20
21              int rpmem_read(RPMEMpool *rpp, void *buff, size_t offset,
22                  size_t length, unsigned lane);
23

DESCRIPTION

25       The rpmem_persist() function copies data of given length at given  off‐
26       set  from  the  associated local memory pool and makes sure the data is
27       persistent on the remote node before the function returns.  The  remote
28       node is identified by the rpp handle which must be returned from either
29       rpmem_open(3) or  rpmem_create(3).   The  offset  is  relative  to  the
30       pool_addr  specified  in the rpmem_open(3) or rpmem_create(3) call.  If
31       the remote pool was created using  rpmem_create()  with  non-NULL  cre‐
32       ate_attr  argument, offset has to be greater or equal to 4096.  In that
33       case the first 4096 bytes of the pool is  used  for  storing  the  pool
34       metadata  and cannot be overwritten.  If the pool was created with NULL
35       create_attr argument, the pool metadata is not stored with the pool and
36       offset  can  be any nonnegative number.  The offset and length combined
37       must not exceed the pool_size passed  to  rpmem_open(3)  or  rpmem_cre‐
38       ate(3).   The  rpmem_persist()  operation  is performed using the given
39       lane number.  The lane must be less than  the  value  returned  by  rp‐
40       mem_open(3)  or  rpmem_create(3) through the nlanes argument (so it can
41       take a value from 0 to nlanes - 1).  The flags argument can be 0 or RP‐
42       MEM_PERSIST_RELAXED  which  means  the  persist  operation will be done
43       without any guarantees regarding atomicity of memory transfer.
44
45       The rpmem_deep_persist() function works in the same way  as  rpmem_per‐
46       sist(3)  function,  but  additionally it flushes the data to the lowest
47       possible  persistency  domain  available  from  software.   Please  see
48       pmem_deep_persist(3) for details.
49
50       The  rpmem_flush()  and  rpmem_drain()  functions are two halves of the
51       single rpmem_persist().  The rpmem_persist() copies data and  makes  it
52       persistent in the one shot, where rpmem_flush() and rpmem_drain() split
53       this operation into two stages.  The rpmem_flush() copies data of given
54       length  at  a given offset from the associated local memory pool to the
55       remote node.  The rpmem_drain() makes sure the data copied in all  pre‐
56       ceding  rpmem_flush() calls is persistent on the remote node before the
57       function returns.  Data copied using rpmem_flush() can not  be  consid‐
58       ered  persistent  on  the  remote node before return from following rp‐
59       mem_drain().  Single rpmem_drain() confirms persistence on  the  remote
60       node of data copied by all rpmem_flush() functions called before it and
61       using the same lane.  The last rpmem_flush() + rpmem_drain() can be re‐
62       placed with rpmem_persist() at no cost.
63
64       The  flags  argument  for rpmem_flush() can be 0 or RPMEM_FLUSH_RELAXED
65       which means the flush operation will be done without any guarantees re‐
66       garding  atomicity  of  memory  transfer.   The  flags argument for rp‐
67       mem_drain() must be 0.
68
69       The   rpmem_flush()   function   performance   is   affected   by   RP‐
70       MEM_WORK_QUEUE_SIZE  environment variable (see librpmem(7) for more de‐
71       tails).
72
73       The rpmem_read() function reads length bytes of data from a remote pool
74       at offset and copies it to the buffer buff.  The operation is performed
75       on the specified lane.  The lane must be less than the  value  returned
76       by  rpmem_open(3) or rpmem_create(3) through the nlanes argument (so it
77       can take a value from 0 to nlanes - 1).  The rpp must point to a remote
78       pool opened or created previously by rpmem_open(3) or rpmem_create(3).
79

RETURN VALUE

81       The  rpmem_persist()  function  returns 0 if the entire memory area was
82       made persistent on the remote node.  Otherwise it  returns  a  non-zero
83       value and sets errno appropriately.
84
85       The  rpmem_flush() function returns 0 if duplication of the memory area
86       to the remote node was initialized successfully.  Otherwise, it returns
87       a non-zero value and sets errno appropriately.
88
89       The  rpmem_drain() function returns 0 if the memory areas duplicated by
90       all rpmem_flush() calls preceding the rpmem_drain() are made persistent
91       on  the  remote  node.  Otherwise, it returns a non-zero value and sets
92       errno appropriately.
93
94       The rpmem_read() function returns 0 if  the  data  was  read  entirely.
95       Otherwise it returns a non-zero value and sets errno appropriately.
96

CAVEATS

98       Ordering  of rpmem_flush() and rpmem_persist() operations which are us‐
99       ing different lane values is not guaranteed.
100

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

CAVEATS

SEE ALSO