pmem2_get_persist_fn(3)

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

NAME

6       pmem2_get_persist_fn() - get a persist function
7

SYNOPSIS

9              #include <libpmem2.h>
10
11              typedef void (*pmem2_persist_fn)(const void *ptr, size_t size);
12
13              struct pmem2_map;
14
15              pmem2_persist_fn pmem2_get_persist_fn(struct pmem2_map *map);
16

DESCRIPTION

18       The pmem2_get_persist_fn() function returns a pointer to a function re‐
19       sponsible for efficiently persisting data in the  range  owned  by  the
20       map.
21
22       Persisting  data  using  pmem2_persist_fn  guarantees  that the data is
23       stored durably by the time it returns.
24
25       There are no alignment restrictions on the range described by  ptr  and
26       size,  but  pmem2_persist_fn  may expand the range as necessary to meet
27       platform alignment requirements.
28
29       There is nothing atomic or transactional about  pmem2_persist_fn.   Any
30       unwritten  stores  in  the given range will be written, but some stores
31       may have already been written by virtue of  normal  cache  eviction/re‐
32       placement  policies.   Correctly written code must not depend on stores
33       waiting until pmem2_persist_fn is called to become  persistent  –  they
34       can become persistent at any time before pmem2_persist_fn is called.
35
36       If  two (or more) mappings share the same pmem2_persist_fn and they are
37       adjacent to each other, it is safe to call this function  for  a  range
38       spanning those mappings.
39
40       Internally pmem2_persist_fn performs two operations:
41
42       • memory  flush  (pmem2_get_flush_fn(3)), which can be reordered by the
43         CPU with other flushes
44
45       • drain (pmem2_get_drain_fn(3)), which makes sure that the flushes  be‐
46         fore this operation won’t be reordered after it
47
48       So this code:
49
50              pmem2_persist_fn persist_fn = pmem2_get_persist_fn(map);
51              persist_fn(addr, len);
52
53       is equivalent of:
54
55              pmem2_flush_fn flush_fn = pmem2_get_flush_fn(map);
56              pmem2_drain_fn drain_fn = pmem2_get_drain_fn(map);
57
58              flush_fn(addr, len);
59              drain_fn();
60
61       Advanced  applications may want to flush multiple discontiguous regions
62       and perform the drain operation only once.
63

RETURN VALUE

65       The pmem2_get_persist_fn() function never returns NULL.
66
67       The pmem2_get_persist_fn() for the same map  always  returns  the  same
68       function.  This means that it’s safe to cache its return value.  Howev‐
69       er, this function is very cheap (because it returns a precomputed  val‐
70       ue), so caching may not be necessary.
71

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

SEE ALSO