1PMEM_MEMMOVE_PERSIST(3) PMDK Programmer's Manual PMEM_MEMMOVE_PERSIST(3)
2
3
4
6 pmem_memmove_persist(), pmem_memcpy_persist(), pmem_memset_persist(),
7 pmem_memmove_nodrain(), pmem_memcpy_nodrain(), pmem_memset_nodrain() --
8 functions that provide optimized copying to persistent memory
9
11 #include <libpmem.h>
12
13 void *pmem_memmove_persist(void *pmemdest, const void *src, size_t len);
14 void *pmem_memcpy_persist(void *pmemdest, const void *src, size_t len);
15 void *pmem_memset_persist(void *pmemdest, int c, size_t len);
16 void *pmem_memmove_nodrain(void *pmemdest, const void *src, size_t len);
17 void *pmem_memcpy_nodrain(void *pmemdest, const void *src, size_t len);
18 void *pmem_memset_nodrain(void *pmemdest, int c, size_t len);
19
21 The pmem_memmove_persist(), pmem_memcpy_persist(), and pmem_memset_per‐
22 sist(), functions provide the same memory copying as their namesakes
23 memmove(3), memcpy(3) and memset(3), and ensure that the result has
24 been flushed to persistence before returning. For example, the follow‐
25 ing code is functionally equivalent to pmem_memmove_persist():
26
27 void *
28 pmem_memmove_persist(void *pmemdest, const void *src, size_t len)
29 {
30 void *retval = memmove(pmemdest, src, len);
31
32 pmem_persist(pmemdest, len);
33
34 return retval;
35 }
36
37 Calling pmem_memmove_persist() may out-perform the above code, however,
38 since the libpmem(7) implementation may take advantage of the fact that
39 pmemdest is persistent memory and use instructions such as non-temporal
40 stores to avoid the need to flush processor caches.
41
42 WARNING: Using these functions where pmem_is_pmem(3) returns
43 false may not do anything useful. Use the normal libc functions
44 in that case.
45
46 The pmem_memmove_nodrain(), pmem_memcpy_nodrain() and pmem_mem‐
47 set_nodrain() functions are similar to pmem_memmove_persist(),
48 pmem_memcpy_persist(), and pmem_memset_persist() described above, ex‐
49 cept they skip the final pmem_drain() step. This allows applications
50 to optimize cases where several ranges are being copied to persistent
51 memory, followed by a single call to pmem_drain(). The following exam‐
52 ple illustrates how these functions might be used to avoid multiple
53 calls to pmem_drain() when copying several ranges of memory to pmem:
54
55 /* ... write several ranges to pmem ... */
56 pmem_memcpy_nodrain(pmemdest1, src1, len1);
57 pmem_memcpy_nodrain(pmemdest2, src2, len2);
58
59 /* ... */
60
61 /* wait for any pmem stores to drain from HW buffers */
62 pmem_drain();
63
65 The pmem_memmove_persist(), pmem_memcpy_persist(), pmem_memset_per‐
66 sist(), pmem_memmove_nodrain(), pmem_memcpy_nodrain() and pmem_mem‐
67 set_nodrain() functions return the address of the destination.
68
70 After calling any of the _nodrain functions (pmem_memmove_nodrain(),
71 pmem_memcpy_nodrain() or pmem_memset_nodrain()) you should not expect
72 memory to be visible to other threads before calling pmem_drain(3) or
73 any of the _persist functions. This is because those functions may use
74 non-temporal store instructions, which are weakly ordered. See "Intel
75 64 and IA-32 Architectures Software Developer's Manual", Volume 1,
76 "Caching of Temporal vs. Non-Temporal Data" section for details.
77
79 memcpy(3), memmove(3), memset(3), libpmem(7) and <http://pmem.io>
80
81
82
83PMDK - pmem API version 1.1 2018-03-13 PMEM_MEMMOVE_PERSIST(3)