NAME

       libpmem2_unsafe_shutdown - libpmem2 unsafe shutdown

DESCRIPTION

       In  systems with the persistent memory support, a power-fail protected domain covers a set
       of resources from which the platform will flush data to the persistent medium in case of a
       power-failure.  Data stored on the persistent medium is preserved across power cycles.

       The  hardware  guarantees the feature to flush all data stored in the power-fail protected
       domain to the persistent medium.  However, nothing is infallible,  and  Persistent  Memory
       hardware  can  expose  a  monotonically  increasing  unsafe shutdown counter (USC) 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.

              Note:  The unsafe shutdown 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 file below.

UNSAFE SHUTDOWN DETECTION

       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.

       Applications  can  implement  a  detection  mechanism  by  storing  the USC retrieved from
       pmem2_source_device_usc(3) in Persistent Memory.  Then, on subsequent startups, the stored
       value must be compared with a newly retrieved one.

       However,  this  detection  method  can  result  in  false-positives.   Moving  the file to
       different Persistent Memory devices with possibly different USC values would lead to false
       unsafe shutdown detection.

       Additionally,  relying on USC 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.

       Applications  can  avoid false-positives associated with moving the file by storing device
       identification, obtained  through  pmem2_source_device_id(3),  alongside  the  USC.   This
       enables  the  software to check if the underlying device has changed, and reinitialize the
       stored USC in such cases.

       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.

       The application should use pmem2_deep_flush(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.

       General-purpose software should not assume the presence of USC on the platform, and should
       instead appropriately handle any PMEM2_E_NOSUPP  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.

SEE ALSO

       pmem2_deep_flush(3),            pmem2_persist_fn(3),            pmem2_source_device_id(3),
       pmem2_source_device_usc(3) and <https://pmem.io>