NAME

       pmem_flush(),   pmem_drain(),   pmem_persist(),   pmem_msync(),   pmem_deep_flush(),   pmem_deep_drain(),
       pmem_deep_persist(), pmem_has_hw_drain(), pmem_has_auto_flush() -  check  persistency,  store  persistent
       data and delete mappings

SYNOPSIS

              #include <libpmem.h>

              void pmem_persist(const void *addr, size_t len);
              int pmem_msync(const void *addr, size_t len);
              void pmem_flush(const void *addr, size_t len);
              void pmem_deep_flush(const void *addr, size_t len); (EXPERIMENTAL)
              int pmem_deep_drain(const void *addr, size_t len); (EXPERIMENTAL)
              int pmem_deep_persist(const void *addr, size_t len); (EXPERIMENTAL)
              void pmem_drain(void);
              int pmem_has_auto_flush(void); (EXPERIMENTAL)
              int pmem_has_hw_drain(void);

DESCRIPTION

       The  functions  in  this  section  provide  access to the stages of flushing to persistence, for the less
       common cases where an application needs more control of the flushing operations than  the  pmem_persist()
       function.

              WARNING:  Using  pmem_persist() on a range where pmem_is_pmem(3) returns false may not do anything
              useful – use msync(2) instead.

       The pmem_persist() function force any changes in the range [addr,  addr+len)  to  be  stored  durably  in
       persistent memory.  This is equivalent to calling msync(2) but may be more optimal and will avoid calling
       into the kernel if possible.  There are no alignment restrictions on the range described by addr and len,
       but pmem_persist() may expand the range as necessary to meet platform alignment requirements.

              WARNING:  Like  msync(2), there is nothing atomic or transactional about this call.  Any unwritten
              stores in the given range will be written, but some stores may have already been written by virtue
              of  normal  cache eviction/replacement policies.  Correctly written code must not depend on stores
              waiting until pmem_persist() is called to become persistent – they can become  persistent  at  any
              time before pmem_persist() is called.

       The  pmem_msync()  function  is  like  pmem_persist()  in  that it forces any changes in the range [addr,
       addr+len) to be stored durably.  Since it calls msync(), this function works on either persistent  memory
       or  a  memory  mapped  file  on traditional storage.  pmem_msync() takes steps to ensure the alignment of
       addresses and lengths passed to msync() meet the requirements of that system call.  It calls msync() with
       the  MS_SYNC  flag  as described in msync(2).  Typically the application only checks for the existence of
       persistent memory once, and then uses that result throughout the program, for example:

              /* do this call once, after the pmem is memory mapped */
              int is_pmem = pmem_is_pmem(rangeaddr, rangelen);

              /* ... make changes to a range of pmem ... */

              /* make the changes durable */
              if (is_pmem)
                  pmem_persist(subrangeaddr, subrangelen);
              else
                  pmem_msync(subrangeaddr, subrangelen);

              /* ... */

              WARNING: On Linux, pmem_msync() and msync(2) have no effect on memory ranges  mapped  from  Device
              DAX.   In case of memory ranges where pmem_is_pmem(3) returns true use pmem_persist() to force the
              changes to be stored durably in persistent memory.

       The pmem_flush() and pmem_drain() functions provide partial  versions  of  the  pmem_persist()  function.
       pmem_persist() can be thought of as this:

              void
              pmem_persist(const void *addr, size_t len)
              {
                  /* flush the processor caches */
                  pmem_flush(addr, len);

                  /* wait for any pmem stores to drain from HW buffers */
                  pmem_drain();
              }

       These functions allow advanced programs to create their own variations of pmem_persist().  For example, a
       program that needs to flush several discontiguous ranges can call pmem_flush() for each  range  and  then
       follow up by calling pmem_drain() once.

       The   semantics  of  pmem_deep_flush()  function  is  the  same  as  pmem_flush()  function  except  that
       pmem_deep_flush() is indifferent to  PMEM_NO_FLUSH  environment  variable  (see  ENVIRONMENT  section  in
       libpmem(7)) and always flushes processor caches.

       The  behavior  of  pmem_deep_persist()  function  is  the same as pmem_persist(), except that it provides
       higher reliability by flushing persistent memory stores to the most reliable persistence domain available
       to software rather than depending on automatic WPQ (write pending queue) flush on power failure (ADR).

       The  pmem_deep_flush()  and  pmem_deep_drain()  functions provide partial versions of pmem_deep_persist()
       function.  pmem_deep_persist() can be thought of as this:

              int pmem_deep_persist(const void *addr, size_t len)
              {
                  /* flush the processor caches */
                  pmem_deep_flush(addr, len);

                  /* wait for any pmem stores to drain from HW buffers */
                  return pmem_deep_drain(addr, len);
              }

       Since this operation is usually much more expensive  than  pmem_persist(),  it  should  be  used  rarely.
       Typically  the  application  should  use  this  function  only to flush the most critical data, which are
       required to recover after the power failure.

       The pmem_has_auto_flush() function checks if the machine supports automatic  CPU  cache  flush  on  power
       failure  or  system  crash.  Function returns true only when each NVDIMM in the system is covered by this
       mechanism.

       The pmem_has_hw_drain() function checks if the machine supports an explicit  hardware  drain  instruction
       for persistent memory.

RETURN VALUE

       The pmem_persist() function returns no value.

       The  pmem_msync()  return  value  is  the  return  value of msync(), which can return -1 and set errno to
       indicate an error.

       The pmem_flush(), pmem_drain() and pmem_deep_flush() functions return no value.

       The pmem_deep_persist() and pmem_deep_drain() return 0 on success.  Otherwise  it  returns  -1  and  sets
       errno  appropriately.   If  len  is  equal zero pmem_deep_persist() and pmem_deep_drain() return 0 but no
       flushing take place.

       The pmem_has_auto_flush() function returns 1 if given platform supports processor  cache  flushing  on  a
       power loss event.  Otherwise it returns 0.  On error it returns -1 and sets errno appropriately.

       The  pmem_has_hw_drain()  function  returns  true  if  the  machine  supports  an explicit hardware drain
       instruction for persistent memory.  On Intel processors with  persistent  memory,  stores  to  persistent
       memory  are  considered  persistent  once  they  are flushed from the CPU caches, so this function always
       returns false.  Despite that, programs using pmem_flush() to flush ranges of memory should  still  follow
       up  by  calling pmem_drain() once to ensure the flushes are complete.  As mentioned above, pmem_persist()
       handles calling both pmem_flush() and pmem_drain().

SEE ALSO

       msync(2), pmem_is_pmem(3), libpmem(7) and <https://pmem.io>