pmemobj_drain(3)

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

NAME

6       pmemobj_memcpy_persist(),  pmemobj_memset_persist(), pmemobj_persist(),
7       pmemobj_flush(), pmemobj_drain() -- low-level memory manipulation func‐
8       tions
9

SYNOPSIS

11              #include <libpmemobj.h>
12
13              void *pmemobj_memcpy_persist(PMEMobjpool *pop, void *dest,
14                  const void *src, size_t len);
15              void *pmemobj_memset_persist(PMEMobjpool *pop, void *dest,
16                  int c, size_t len);
17              void pmemobj_persist(PMEMobjpool *pop, const void *addr,
18                  size_t len);
19              void pmemobj_flush(PMEMobjpool *pop, const void *addr,
20                  size_t len);
21              void pmemobj_drain(PMEMobjpool *pop);
22

DESCRIPTION

24       The  libpmemobj-specific  low-level  memory  manipulation functions de‐
25       scribed here leverage the knowledge of the additional configuration op‐
26       tions available for libpmemobj(7) pools, such as replication.  They al‐
27       so take advantage of the type of storage behind the pool and use appro‐
28       priate  flush/drain functions.  It is advised to use these functions in
29       conjunction with libpmemobj(7) objects rather than using low-level mem‐
30       ory manipulation functions from libpmem.
31
32       The  pmemobj_memcpy_persist()  and  pmemobj_memset_persist()  functions
33       provide the same memory copying as their namesakes memcpy(3), and  mem‐
34       set(3),  and ensure that the result has been flushed to persistence be‐
35       fore returning.
36
37       pmemobj_persist() forces any changes in the range [addr,  addr+len)  to
38       be  stored  durably in persistent memory.  Internally this may call ei‐
39       ther pmem_msync(3) or pmem_persist(3).  There are no alignment restric‐
40       tions on the range described by addr and len, but pmemobj_persist() may
41       expand the range as necessary to meet platform alignment requirements.
42
43              WARNING: Like msync(2), there is nothing atomic or transactional
44              about  this  call.  Any unwritten stores in the given range will
45              be written, but some stores may have  already  been  written  by
46              virtue of normal cache eviction/replacement policies.  Correctly
47              written code must not depend  on  stores  waiting  until  pmemo‐
48              bj_persist()  is  called  to become persistent - they can become
49              persistent at any time before pmemobj_persist() is called.
50
51       The pmemobj_flush() and pmemobj_drain() functions provide partial  ver‐
52       sions  of  the pmemobj_persist() function described above.  These func‐
53       tions allow advanced programs to create their own variations of  pmemo‐
54       bj_persist().   For example, a program that needs to flush several dis‐
55       contiguous ranges can call pmemobj_flush() for each range and then fol‐
56       low  up  by calling pmemobj_drain() once.  For more information on par‐
57       tial flushing operations, see pmem_flush(3).
58

RETURN VALUE

60       The pmemobj_memcpy_persist() and pmemobj_memset_persist() functions re‐
61       turn the same values as their namesakes memcpy(3), and memset(3).
62
63       pmemobj_persist(), pmemobj_flush() and pmemobj_drain() return no value.
64

EXAMPLES

66       The  following  code  is functionally equivalent to pmemobj_memcpy_per‐
67       sist():
68
69              void *
70              pmemobj_memcpy_persist(PMEMobjpool *pop, void *dest,
71                  const void *src, size_t len)
72              {
73                  void *retval = memcpy(dest, src, len);
74
75                  pmemobj_persist(pop, dest, len);
76
77                  return retval;
78              }
79
80       pmemobj_persist() can be thought of as this:
81
82              void
83              pmemobj_persist(PMEMobjpool *pop, const void *addr, size_t len)
84              {
85                  /* flush the processor caches */
86                  pmemobj_flush(pop, addr, len);
87
88                  /* wait for any pmem stores to drain from HW buffers */
89                  pmemobj_drain(pop);
90              }
91

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

EXAMPLES

SEE ALSO