pmem2_get_memmove_fn(3)

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

NAME

6       pmem2_get_memmove_fn(),  pmem2_get_memset_fn(), pmem2_get_memcpy_fn() -
7       get a function that provides optimized copying to persistent memory
8

SYNOPSIS

10              #include <libpmem2.h>
11
12              typedef void *(*pmem2_memmove_fn)(void *pmemdest, const void *src, size_t len,
13                      unsigned flags);
14              typedef void *(*pmem2_memcpy_fn)(void *pmemdest, const void *src, size_t len,
15                      unsigned flags);
16              typedef void *(*pmem2_memset_fn)(void *pmemdest, int c, size_t len,
17                      unsigned flags);
18
19              struct pmem2_map;
20
21              pmem2_memmove_fn pmem2_get_memmove_fn(struct pmem2_map *map);
22              pmem2_memset_fn pmem2_get_memset_fn(struct pmem2_map *map);
23              pmem2_memcpy_fn pmem2_get_memcpy_fn(struct pmem2_map *map);
24

DESCRIPTION

26       The   pmem2_get_memmove_fn(),   pmem2_get_memset_fn(),   pmem2_get_mem‐
27       cpy_fn() functions return a pointer to a function responsible for effi‐
28       cient storing and flushing of data for mapping map.
29
30       pmem2_memmove_fn(), pmem2_memset_fn() and  pmem2_memcpy_fn()  functions
31       provide the same memory copying functionalities as their namesakes mem‐
32       move(3), memcpy(3) and memset(3), and ensure that the result  has  been
33       flushed  to  persistence  before  returning (unless PMEM2_F_MEM_NOFLUSH
34       flag was used).
35
36       For example, the following code:
37
38                      memmove(dest, src, len);
39                      pmem2_persist_fn persist_fn = pmem2_get_persist_fn(map);
40                      persist_fn(dest, len);
41
42       is functionally equivalent to:
43
44                      pmem2_memmove_fn memmove_fn = pmem2_get_memmove_fn(map);
45                      memmove_fn(dest, src, len, 0);
46
47       Unlike libc implementation, libpmem2 functions guarantee that if desti‐
48       nation  buffer  address  and  length are 8 byte aligned then all stores
49       will be performed using at least 8 byte store instructions.  This means
50       that a series of 8 byte stores followed by persist_fn can be safely re‐
51       placed by a single memmove_fn call.
52
53       The flags argument of all of the above functions has the same  meaning.
54       It can be 0 or a bitwise OR of one or more of the following flags:
55
56       • PMEM2_F_MEM_NODRAIN  -  modifies  the  behavior  to  skip  the  final
57         pmem2_drain_fn step.  This  allows  applications  to  optimize  cases
58         where  several ranges are being copied to persistent memory, followed
59         by a single call to pmem2_drain_fn.   The  following  example  illus‐
60         trates  how  this  flag  might  be  used  to  avoid multiple calls to
61         pmem2_drain_fn when copying several ranges of memory to pmem:
62
63         pmem2_memcpy_fn memcpy_fn = pmem2_get_memcpy_fn(map);
64         pmem2_drain_fn drain_fn = pmem2_get_drain_fn(map);
65
66         /* ... write several ranges to pmem ... */
67         memcpy_fn(pmemdest1, src1, len1, PMEM2_F_MEM_NODRAIN);
68         memcpy_fn(pmemdest2, src2, len2, PMEM2_F_MEM_NODRAIN);
69
70         /* ... */
71
72         /* wait for any pmem stores to drain from HW buffers */
73         drain_fn();
74
75       • PMEM2_F_MEM_NOFLUSH   -   Don't   flush   anything.    This   implies
76         PMEM2_F_MEM_NODRAIN.  Using this flag only makes sense when it's fol‐
77         lowed by any function that flushes data.
78
79       The remaining flags say how the operation should be done, and are mere‐
80       ly hints.
81
82       • PMEM2_F_MEM_NONTEMPORAL  -  Use non-temporal instructions.  This flag
83         is mutually exclusive with PMEM2_F_MEM_TEMPORAL.  On x86_64 this flag
84         is mutually exclusive with PMEM2_F_MEM_NOFLUSH.
85
86       • PMEM2_F_MEM_TEMPORAL - Use temporal instructions.  This flag is mutu‐
87         ally exclusive with PMEM2_F_MEM_NONTEMPORAL.
88
89       • PMEM2_F_MEM_WC - Use write combining mode.  This flag is mutually ex‐
90         clusive  with PMEM2_F_MEM_WB.  On x86_64 this flag is mutually exclu‐
91         sive with PMEM2_F_MEM_NOFLUSH.
92
93       • PMEM2_F_MEM_WB - Use write back mode.  This flag is  mutually  exclu‐
94         sive   with   PMEM2_F_MEM_WC.    On  x86_64  this  is  an  alias  for
95         PMEM2_F_MEM_TEMPORAL.
96
97       Using an invalid combination of flags has undefined behavior.
98
99       Without any of the above flags libpmem2 will  try  to  guess  the  best
100       strategy  based on the data size.  See PMEM_MOVNT_THRESHOLD description
101       in libpmem2(7) for details.
102

RETURN VALUE

104       The   pmem2_get_memmove_fn(),   pmem2_get_memset_fn(),   pmem2_get_mem‐
105       cpy_fn() functions never return NULL.
106
107       They return the same function for the same mapping.
108
109       This means that it's safe to cache their return values.  However, these
110       functions are very cheap (because their return values are precomputed),
111       so caching may not be necessary.
112
113       If  two  (or more) mappings share the same pmem2_memmove_fn, pmem2_mem‐
114       set_fn, pmem2_memcpy_fn and they are adjacent to each other, it is safe
115       to call these functions for a range spanning those mappings.
116

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

SEE ALSO