PMEM_MEMMOVE_PERSIST(3)

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>