pmem_memcpy_persist(3)

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
74       The remaining flags say how the operation should be done, and are mere‐
75       ly hints.
76
77       · PMEM_F_MEM_NONTEMPORAL - Use non-temporal instructions.  This flag is
78         mutually  exclusive with PMEM_F_MEM_TEMPORAL.  On x86_64 this flag is
79         mutually exclusive with PMEM_F_MEM_NOFLUSH.
80
81       · PMEM_F_MEM_TEMPORAL - Use temporal instructions.  This flag is  mutu‐
82         ally exclusive with PMEM_F_MEM_NONTEMPORAL.
83
84       · PMEM_F_MEM_WC  - Use write combining mode.  This flag is mutually ex‐
85         clusive  with  PMEM_F_MEM_WB.   On  x86_64  this  is  an  alias   for
86         PMEM_F_MEM_NONTEMPORAL.   On  x86_64  this flag is mutually exclusive
87         with PMEM_F_MEM_NOFLUSH.
88
89       · PMEM_F_MEM_WB - Use write back mode.  This flag is mutually exclusive
90         with PMEM_F_MEM_WC.  On x86_64 this is an alias for PMEM_F_MEM_TEMPO‐
91         RAL.
92
93       Using an invalid combination of flags has undefined behavior.
94
95       Without any of the above flags libpmem  will  try  to  guess  the  best
96       strategy  based on size.  See PMEM_MOVNT_THRESHOLD description in libp‐
97       mem(7) for details.
98
99       pmem_memmove_persist() is an alias for pmem_memmove() with flags  equal
100       to 0.
101
102       pmem_memcpy_persist() is an alias for pmem_memcpy() with flags equal to
103       0.
104
105       pmem_memset_persist() is an alias for pmem_memset() with flags equal to
106       0.
107
108       pmem_memmove_nodrain()  is an alias for pmem_memmove() with flags equal
109       to PMEM_F_MEM_NODRAIN.
110
111       pmem_memcpy_nodrain() is an alias for pmem_memcpy() with flags equal to
112       PMEM_F_MEM_NODRAIN.
113
114       pmem_memset_nodrain() is an alias for pmem_memset() with flags equal to
115       PMEM_F_MEM_NODRAIN.
116

RETURN VALUE

118       All of the above functions return address of the destination buffer.
119

CAVEATS

121       After calling any of the functions  with  PMEM_F_MEM_NODRAIN  flag  you
122       should  not expect memory to be visible to other threads before calling
123       pmem_drain(3) or any of the _persist functions.   This  is  because  on
124       x86_64  those  functions may use non-temporal store instructions, which
125       are weakly ordered.  See “Intel 64 and IA-32 Architectures Software De‐
126       veloper's  Manual”, Volume 1, “Caching of Temporal vs. Non-Temporal Da‐
127       ta” section for details.
128

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

CAVEATS

SEE ALSO