rpmem_persist(3)

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

NAME

6       rpmem_persist()(DEPRECATED),    rpmem_deep_persist()(DEPRECATED),   rp‐
7       mem_flush()(DEPRECATED), rpmem_drain()(DEPRECATED), rpmem_read()(DEPRE‐
8       CATED) - functions to copy and read remote pools
9

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

CAVEATS

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

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

CAVEATS

SEE ALSO