NAME

       pmem_memmove_persist(),            pmem_memcpy_persist(),           pmem_memset_persist(),
       pmem_memmove_nodrain(),  pmem_memcpy_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)  implementation  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  illustrates  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_memset_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 instructions, 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>