NAME

       pmem_memmove_persist(),  pmem_memcpy_persist(),  pmem_memset_persist(), pmem_memmove_nodrain(), pmem_mem‐
       cpy_nodrain(), pmem_memset_nodrain() - functions that provide optimized copying to persistent memory

SYNOPSIS

              #include <libpmem.h>

              void *pmem_memmove_persist(void *pmemdest, const void *src, size_t len);
              void *pmem_memcpy_persist(void *pmemdest, const void *src, size_t len);
              void *pmem_memset_persist(void *pmemdest, int c, size_t len);
              void *pmem_memmove_nodrain(void *pmemdest, const void *src, size_t len);
              void *pmem_memcpy_nodrain(void *pmemdest, const void *src, size_t len);
              void *pmem_memset_nodrain(void *pmemdest, int c, size_t len);

DESCRIPTION

       The pmem_memmove_persist(), pmem_memcpy_persist(), and pmem_memset_persist(), functions provide the  same
       memory  copying  as  their  namesakes memmove(3), memcpy(3) and memset(3), and ensure that the result has
       been flushed to persistence before returning.  For example, the following code is functionally equivalent
       to pmem_memmove_persist():

              void *
              pmem_memmove_persist(void *pmemdest, const void *src, size_t len)
              {
                  void *retval = memmove(pmemdest, src, len);

                  pmem_persist(pmemdest, len);

                  return retval;
              }

       Calling pmem_memmove_persist() may out-perform the above code, however, since the libpmem(7)  implementa‐
       tion  may  take  advantage  of  the  fact that pmemdest is persistent memory and use instructions such as
       non-temporal stores to avoid the need to flush processor caches.

              WARNING: Using these functions where pmem_is_pmem(3) returns false may  not  do  anything  useful.
              Use the normal libc functions in that case.

       The  pmem_memmove_nodrain(),  pmem_memcpy_nodrain()  and  pmem_memset_nodrain()  functions are similar to
       pmem_memmove_persist(), pmem_memcpy_persist(), and pmem_memset_persist()  described  above,  except  they
       skip  the  final  pmem_drain() step.  This allows applications to optimize cases where several ranges are
       being copied to persistent memory, followed by a single call to pmem_drain().  The following example  il‐
       lustrates  how these functions might be used to avoid multiple calls to pmem_drain() when copying several
       ranges of memory to pmem:

              /* ... write several ranges to pmem ... */
              pmem_memcpy_nodrain(pmemdest1, src1, len1);
              pmem_memcpy_nodrain(pmemdest2, src2, len2);

              /* ... */

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

RETURN VALUE

       The   pmem_memmove_persist(),   pmem_memcpy_persist(),   pmem_memset_persist(),   pmem_memmove_nodrain(),
       pmem_memcpy_nodrain() and pmem_memset_nodrain() functions return the address of the destination.

CAVEATS

       After  calling  any of the _nodrain functions (pmem_memmove_nodrain(), pmem_memcpy_nodrain() or pmem_mem‐
       set_nodrain()) you should not expect memory to be visible to other threads before  calling  pmem_drain(3)
       or  any  of  the _persist functions.  This is because those functions may use non-temporal store instruc‐
       tions, which are weakly ordered.  See “Intel 64 and IA-32  Architectures  Software  Developer's  Manual”,
       Volume 1, “Caching of Temporal vs. Non-Temporal Data” section for details.

SEE ALSO

       memcpy(3), memmove(3), memset(3), libpmem(7) and <http://pmem.io>

PMDK - pmem API version 1.1                        2018-05-21                            PMEM_MEMMOVE_PERSIST(3)