pmem_memcpy_persist(3)

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

NAME

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

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

CAVEATS

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

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

CAVEATS

SEE ALSO