libpmem2_unsafe_shutdown(7)

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

NAME

6       libpmem2_unsafe_shutdown - libpmem2 unsafe shutdown
7

DESCRIPTION

9       In  systems  with the persistent memory support, a power-fail protected
10       domain covers a set of resources from which the platform will flush da‐
11       ta to the persistent medium in case of a power-failure.  Data stored on
12       the persistent medium is preserved across power cycles.
13
14       The hardware guarantees the feature to flush all  data  stored  in  the
15       power-fail protected domain to the persistent medium.  However, nothing
16       is infallible, and Persistent Memory hardware can expose a monotonical‐
17       ly  increasing  unsafe shutdown counter (USC) that is incremented every
18       time a failure of the mechanism above is detected.  This  allows  soft‐
19       ware to discover situations where a running application was interrupted
20       by a power failure that led to an unsafe shutdown.  Undiscovered unsafe
21       shutdowns might cause silent data corruption.
22
23              Note:  The  unsafe shutdown may corrupt data stored on a device,
24              in a file, in a set of files, and a mapping spanning only a part
25              of  a  file.  For the sake of simplicity, all of the above cases
26              will be called file below.
27

UNSAFE SHUTDOWN DETECTION

29       Software can detect an unsafe shutdown by watching for the  change  be‐
30       tween  unsafe  shutdown  count  value across application startups.  Any
31       changes can be indicative of unsafe shutdown occurrence.
32
33       Applications can implement a detection mechanism by storing the USC re‐
34       trieved from pmem2_source_device_usc(3) in Persistent Memory.  Then, on
35       subsequent startups, the stored value must be compared with a newly re‐
36       trieved one.
37
38       However,  this  detection method can result in false-positives.  Moving
39       the file to different Persistent Memory devices with possibly different
40       USC values would lead to false unsafe shutdown detection.
41
42       Additionally,  relying on USC value alone could result in the detection
43       of unsafe shutdown events that occur when such a shutdown has no chance
44       of  impacting  the  data used by the application, e.g., when nothing is
45       actively using the file.
46
47       Applications can avoid false-positives associated with moving the  file
48       by  storing  device  identification,  obtained through pmem2_source_de‐
49       vice_id(3), alongside the USC.  This enables the software to  check  if
50       the  underlying  device has changed, and reinitialize the stored USC in
51       such cases.
52
53       The second behavior, detection of possibly irrelevant  unsafe  shutdown
54       events,  if  undesirable, can be prevented by storing a flag indicating
55       whether the file is in use, alongside all the rest of the relevant  in‐
56       formation.
57
58       The  application  should  use pmem2_deep_flush(3) when storing any data
59       related to unsafe shutdown  detection  for  higher  reliability.   This
60       helps ensure that the detection mechanism is not reliant on the correct
61       functioning of the same hardware features it is designed to safeguard.
62
63       General-purpose software should not assume the presence of USC  on  the
64       platform, and should instead appropriately handle any PMEM2_E_NOSUPP it
65       encounters.  Doing otherwise might cause the software to be unnecessar‐
66       ily restrictive about the hardware it supports and would prevent, e.g.,
67       testing on emulated PMEM.
68

NAME

DESCRIPTION

UNSAFE SHUTDOWN DETECTION

SEE ALSO