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

NAME

6       pmem_memmove(),  pmem_memcpy(),  pmem_memset(), pmem_memmove_persist(),
7       pmem_memcpy_persist(),  pmem_memset_persist(),  pmem_memmove_nodrain(),
8       pmem_memcpy_nodrain(),  pmem_memset_nodrain()  - functions that provide
9       optimized copying to persistent memory
10

SYNOPSIS

12              #include <libpmem.h>
13
14              void *pmem_memmove(void *pmemdest, const void *src, size_t len, unsigned flags);
15              void *pmem_memcpy(void *pmemdest, const void *src, size_t len, unsigned flags);
16              void *pmem_memset(void *pmemdest, int c, size_t len, unsigned flags);
17              void *pmem_memmove_persist(void *pmemdest, const void *src, size_t len);
18              void *pmem_memcpy_persist(void *pmemdest, const void *src, size_t len);
19              void *pmem_memset_persist(void *pmemdest, int c, size_t len);
20              void *pmem_memmove_nodrain(void *pmemdest, const void *src, size_t len);
21              void *pmem_memcpy_nodrain(void *pmemdest, const void *src, size_t len);
22              void *pmem_memset_nodrain(void *pmemdest, int c, size_t len);
23

DESCRIPTION

25       pmem_memmove(), pmem_memcpy() and pmem_memset() functions  provide  the
26       same  memory  copying as their namesakes memmove(3), memcpy(3) and mem‐
27       set(3), and ensure that the result has been flushed to persistence  be‐
28       fore returning (unless PMEM_F_MEM_NOFLUSH flag was used).
29
30       For example, the following code is functionally equivalent to pmem_mem‐
31       move() (with flags equal to 0):
32
33                  memmove(dest, src, len);
34                  pmem_persist(dest, len);
35
36       Calling pmem_memmove() may out-perform the above  code,  because  libp‐
37       mem(7)  implementation  may take advantage of the fact that pmemdest is
38       persistent memory and use instructions such as non-temporal  stores  to
39       avoid the need to flush processor caches.
40
41              WARNING:  Using  these  functions  where pmem_is_pmem(3) returns
42              false may not do anything useful.  Use libc  functions  in  that
43              case.
44
45       Unlike  libc implementation, libpmem functions guarantee that if desti‐
46       nation buffer address and length are 8 byte  aligned  then  all  stores
47       will be performed using at least 8 byte store instructions.  This means
48       that a series of 8 byte stores followed by pmem_persist(3) can be safe‐
49       ly replaced by a single call to one of the above functions.
50
51       The  flags argument of all of the above functions has the same meaning.
52       It can be 0 or a bitwise OR of one or more of the following flags:
53
54       • PMEM_F_MEM_NODRAIN  -  modifies  the  behavior  to  skip  the   final
55         pmem_drain()  step.  This allows applications to optimize cases where
56         several ranges are being copied to persistent memory, followed  by  a
57         single  call  to pmem_drain().  The following example illustrates how
58         this flag might be used to avoid multiple calls to pmem_drain()  when
59         copying several ranges of memory to pmem:
60
61         /* ... write several ranges to pmem ... */
62         pmem_memcpy(pmemdest1, src1, len1, PMEM_F_MEM_NODRAIN);
63         pmem_memcpy(pmemdest2, src2, len2, PMEM_F_MEM_NODRAIN);
64
65         /* ... */
66
67         /* wait for any pmem stores to drain from HW buffers */
68         pmem_drain();
69
70       • PMEM_F_MEM_NOFLUSH    -   Don’t   flush   anything.    This   implies
71         PMEM_F_MEM_NODRAIN.  Using this flag only makes sense when it’s  fol‐
72         lowed by any function that flushes data.
73