.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "" "" "2023-05-26" "PMDK - " "PMDK Programmer's Manual"
.hy
.\" SPDX-License-Identifier: BSD-3-Clause
.\" Copyright 2020-2021, Intel Corporation
.SH NAME
.PP
\f[B]libpmem2_unsafe_shutdown\f[R] - libpmem2 unsafe shutdown
.SH DESCRIPTION
.PP
In systems with the persistent memory support, \f[I]a power-fail
protected domain\f[R] covers a set of resources from which the platform
will flush data to \f[I]the persistent medium\f[R] in case of \f[I]a
power-failure\f[R].
Data stored on \f[I]the persistent medium\f[R] is preserved across power
cycles.
.PP
The hardware guarantees the feature to flush all data stored in \f[I]the
power-fail protected domain\f[R] to \f[I]the persistent medium\f[R].
However, nothing is infallible, and Persistent Memory hardware can
expose a monotonically increasing \f[I]unsafe shutdown counter\f[R]
(\f[B]USC\f[R]) that is incremented every time a failure of the
mechanism above is detected.
This allows software to discover situations where a running application
was interrupted by a power failure that led to an unsafe shutdown.
Undiscovered unsafe shutdowns might cause silent data corruption.
.RS
.PP
Note: \f[I]The unsafe shutdown\f[R] may corrupt data stored on a device,
in a file, in a set of files, and a mapping spanning only a part of a
file.
For the sake of simplicity, all of the above cases will be called
\f[I]file\f[R] below.
.RE
.SH UNSAFE SHUTDOWN DETECTION
.PP
Software can detect an unsafe shutdown by watching for the change
between unsafe shutdown count value across application startups.
Any changes can be indicative of unsafe shutdown occurrence.
.PP
Applications can implement a detection mechanism by storing the
\f[B]USC\f[R] retrieved from \f[B]pmem2_source_device_usc\f[R](3) in
Persistent Memory.
Then, on subsequent startups, the stored value must be compared with a
newly retrieved one.
.PP
However, this detection method can result in false-positives.
Moving the file to different Persistent Memory devices with possibly
different \f[B]USC\f[R] values would lead to false unsafe shutdown
detection.
.PP
Additionally, relying on \f[B]USC\f[R] value alone could result in the
detection of unsafe shutdown events that occur when such a shutdown has
no chance of impacting the data used by the application, e.g., when
nothing is actively using the file.
.PP
Applications can avoid false-positives associated with moving the file
by storing device identification, obtained through
\f[B]pmem2_source_device_id\f[R](3), alongside the \f[B]USC\f[R].
This enables the software to check if the underlying device has changed,
and reinitialize the stored \f[B]USC\f[R] in such cases.
.PP
The second behavior, detection of possibly irrelevant unsafe shutdown
events, if undesirable, can be prevented by storing a flag indicating
whether the file is in use, alongside all the rest of the relevant
information.
.PP
The application should use \f[B]pmem2_deep_flush\f[R](3) when storing
any data related to unsafe shutdown detection for higher reliability.
This helps ensure that the detection mechanism is not reliant on the
correct functioning of the same hardware features it is designed to
safeguard.
.PP
General-purpose software should not assume the presence of \f[B]USC\f[R]
on the platform, and should instead appropriately handle any
\f[I]PMEM2_E_NOSUPP\f[R] it encounters.
Doing otherwise might cause the software to be unnecessarily restrictive
about the hardware it supports and would prevent, e.g., testing on
emulated PMEM.
.SH SEE ALSO
.PP
\f[B]pmem2_deep_flush\f[R](3), \f[B]pmem2_persist_fn\f[R](3),
\f[B]pmem2_source_device_id\f[R](3),
\f[B]pmem2_source_device_usc\f[R](3) and \f[B]<https://pmem.io>\f[R]