pmemobj_xpersist(3)

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

NAME

6       pmemobj_persist(),    pmemobj_xpersist(),    pmemobj_flush(),    pmemo‐
7       bj_xflush(),  pmemobj_drain(),   pmemobj_memcpy(),   pmemobj_memmove(),
8       pmemobj_memset(),  pmemobj_memcpy_persist(), pmemobj_memset_persist() -
9       low-level memory manipulation functions
10

SYNOPSIS

12              #include <libpmemobj.h>
13
14              void pmemobj_persist(PMEMobjpool *pop, const void *addr,
15                  size_t len);
16              void pmemobj_flush(PMEMobjpool *pop, const void *addr,
17                  size_t len);
18              void pmemobj_drain(PMEMobjpool *pop);
19
20              int pmemobj_xpersist(PMEMobjpool *pop, const void *addr,
21                  size_t len, unsigned flags);
22              int pmemobj_xflush(PMEMobjpool *pop, const void *addr,
23                  size_t len, unsigned flags);
24
25              void *pmemobj_memcpy(PMEMobjpool *pop, void *dest,
26                  const void *src, size_t len, unsigned flags);
27              void *pmemobj_memmove(PMEMobjpool *pop, void *dest,
28                  const void *src, size_t len, unsigned flags);
29              void *pmemobj_memset(PMEMobjpool *pop, void *dest,
30                  int c, size_t len, unsigned flags);
31
32              void *pmemobj_memcpy_persist(PMEMobjpool *pop, void *dest,
33                  const void *src, size_t len);
34              void *pmemobj_memset_persist(PMEMobjpool *pop, void *dest,
35                  int c, size_t len);
36

DESCRIPTION

38       The libpmemobj-specific low-level  memory  manipulation  functions  de‐
39       scribed here leverage the knowledge of the additional configuration op‐
40       tions available for libpmemobj(7) pools, such as replication.  They al‐
41       so take advantage of the type of storage behind the pool and use appro‐
42       priate flush/drain functions.  It is advised to use these functions  in
43       conjunction with libpmemobj(7) objects rather than using low-level mem‐
44       ory manipulation functions from libpmem.
45
46       pmemobj_persist() forces any changes in the range [addr,  addr+len)  to
47       be  stored  durably in persistent memory.  Internally this may call ei‐
48       ther pmem_msync(3) or pmem_persist(3).  There are no alignment restric‐
49       tions on the range described by addr and len, but pmemobj_persist() may
50       expand the range as necessary to meet platform alignment requirements.
51
52              WARNING: Like msync(2), there is nothing atomic or transactional
53              about  this  call.  Any unwritten stores in the given range will
54              be written, but some stores may have  already  been  written  by
55              virtue of normal cache eviction/replacement policies.  Correctly
56              written code must not depend  on  stores  waiting  until  pmemo‐
57              bj_persist()  is  called  to become persistent - they can become
58              persistent at any time before pmemobj_persist() is called.
59
60       The pmemobj_flush() and pmemobj_drain() functions provide partial  ver‐
61       sions  of  the pmemobj_persist() function described above.  These func‐
62       tions allow advanced programs to create their own variations of  pmemo‐
63       bj_persist().   For example, a program that needs to flush several dis‐
64       contiguous ranges can call pmemobj_flush() for each range and then fol‐
65       low  up  by calling pmemobj_drain() once.  For more information on par‐
66       tial flushing operations, see pmem_flush(3).
67
68       pmemobj_xpersist() is a version of pmemobj_persist() function with  ad‐
69       ditional  flags argument.  It supports only the PMEMOBJ_F_RELAXED flag.
70       This flag indicates that memory transfer  operation  does  not  require
71       8-byte atomicity guarantees.
72
73       pmemobj_xflush()  is  a  version of pmemobj_flush() function with addi‐
74       tional flags argument.  It supports only the PMEMOBJ_F_RELAXED flag.
75
76       The pmemobj_memmove(), pmemobj_memcpy() and pmemobj_memset()  functions
77       provide  the  same  memory  copying as their namesakes memmove(3), mem‐
78       cpy(3), and memset(3), and ensure that the result has been  flushed  to
79       persistence  before  returning  (unless  PMEMOBJ_MEM_NOFLUSH  flag  was
80       used).  Valid flags for those functions:
81
82       · PMEMOBJ_F_RELAXED - This flag indicates that memory  transfer  opera‐
83         tion does not require 8-byte atomicity guarantees.
84
85       · PMEMOBJ_F_MEM_NOFLUSH  -  Don't  flush anything.  This implies PMEMO‐
86         BJ_F_MEM_NODRAIN.  Using this flag only makes sense  when  it's  fol‐
87         lowed by any function that flushes data.
88
89       The remaining flags say how the operation should be done, and are mere‐
90       ly hints.
91
92       · PMEMOBJ_F_MEM_NONTEMPORAL - Use non-temporal instructions.  This flag
93         is  mutually  exclusive  with PMEMOBJ_F_MEM_TEMPORAL.  On x86_64 this
94         flag is mutually exclusive with PMEMOBJ_F_MEM_NOFLUSH.
95
96       · PMEMOBJ_F_MEM_TEMPORAL - Use temporal instructions.  This flag is mu‐
97         tually exclusive with PMEMOBJ_F_MEM_NONTEMPORAL.
98
99       · PMEMOBJ_F_MEM_WC  -  Use write combining mode.  This flag is mutually
100         exclusive with PMEMOBJ_F_MEM_WB.  On x86_64  this  is  an  alias  for
101         PMEMOBJ_F_MEM_NONTEMPORAL.  On x86_64 this flag is mutually exclusive
102         with PMEMOBJ_F_MEM_NOFLUSH.
103
104       · PMEMOBJ_F_MEM_WB - Use write back mode.  This flag is mutually exclu‐
105         sive  with  PMEMOBJ_F_MEM_WC.   On x86_64 this is an alias for PMEMO‐
106         BJ_F_MEM_TEMPORAL.
107
108       pmemobj_memcpy_persist() is an alias for  pmemobj_memcpy()  with  flags
109       equal to 0.
110
111       pmemobj_memset_persist()  is  an  alias for pmemobj_memset() with flags
112       equal to 0.
113

RETURN VALUE

115       pmemobj_memmove(),  pmemobj_memcpy(),  pmemobj_memset(),   pmemobj_mem‐
116       cpy_persist() and pmemobj_memset_persist() return destination buffer.
117
118       pmemobj_persist(),  pmemobj_flush()  and  pmemobj_drain() do not return
119       any value.
120
121       pmemobj_xpersist() and pmemobj_xflush() returns non-zero value and sets
122       errno to EINVAL only if not supported flags has been provided.
123

EXAMPLES

125       The  following  code  is functionally equivalent to pmemobj_memcpy_per‐
126       sist():
127
128              void *
129              pmemobj_memcpy_persist(PMEMobjpool *pop, void *dest,
130                  const void *src, size_t len)
131              {
132                  void *retval = memcpy(dest, src, len);
133
134                  pmemobj_persist(pop, dest, len);
135
136                  return retval;
137              }
138
139       pmemobj_persist() can be thought of as this:
140
141              void
142              pmemobj_persist(PMEMobjpool *pop, const void *addr, size_t len)
143              {
144                  /* flush the processor caches */
145                  pmemobj_flush(pop, addr, len);
146
147                  /* wait for any pmem stores to drain from HW buffers */
148                  pmemobj_drain(pop);
149              }
150

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

EXAMPLES

SEE ALSO