NAME¶

SYNOPSIS¶

#include <libpmem.h>
void *pmem_memmove(void *pmemdest, const void *src, size_t len, unsigned flags);
void *pmem_memcpy(void *pmemdest, const void *src, size_t len, unsigned flags);
void *pmem_memset(void *pmemdest, int c, size_t len, unsigned flags);
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¶

For example, the following code is functionally equivalent to pmem_memmove() (with flags equal to 0):

    memmove(dest, src, len);
    pmem_persist(dest, len);

    

Calling pmem_memmove() may out-perform the above code, because 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.

Unlike libc implementation, libpmem functions guarantee that if destination buffer address and length are 8 byte aligned then all stores will be performed using at least 8 byte store instructions. This means that a series of 8 byte stores followed by pmem_persist(3) can be safely replaced by a single call to one of the above functions.

The flags argument of all of the above functions has the same meaning. It can be 0 or a bitwise OR of one or more of the following flags:

•

PMEM_F_MEM_NODRAIN - modifies the behavior to 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 this flag 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(pmemdest1, src1, len1, PMEM_F_MEM_NODRAIN);
pmem_memcpy(pmemdest2, src2, len2, PMEM_F_MEM_NODRAIN);
/* ... */
/* wait for any pmem stores to drain from HW buffers */
pmem_drain();

    

•

PMEM_F_MEM_NOFLUSH - Don’t flush anything. This implies PMEM_F_MEM_NODRAIN. Using this flag only makes sense when it’s followed by any function that flushes data.

The remaining flags say how the operation should be done, and are merely hints.

•

PMEM_F_MEM_NONTEMPORAL - Use non-temporal instructions. This flag is mutually exclusive with PMEM_F_MEM_TEMPORAL. On x86_64 this flag is mutually exclusive with PMEM_F_MEM_NOFLUSH.

•

PMEM_F_MEM_TEMPORAL - Use temporal instructions. This flag is mutually exclusive with PMEM_F_MEM_NONTEMPORAL.

•

PMEM_F_MEM_WC - Use write combining mode. This flag is mutually exclusive with PMEM_F_MEM_WB. On x86_64 this flag is mutually exclusive with PMEM_F_MEM_NOFLUSH.

•

PMEM_F_MEM_WB - Use write back mode. This flag is mutually exclusive with PMEM_F_MEM_WC. On x86_64 this is an alias for PMEM_F_MEM_TEMPORAL.

Using an invalid combination of flags has undefined behavior.

Without any of the above flags libpmem will try to guess the best strategy based on size. See PMEM_MOVNT_THRESHOLD description in libpmem(7) for details.

pmem_memmove_persist() is an alias for pmem_memmove() with flags equal to 0.

pmem_memcpy_persist() is an alias for pmem_memcpy() with flags equal to 0.

pmem_memset_persist() is an alias for pmem_memset() with flags equal to 0.

pmem_memmove_nodrain() is an alias for pmem_memmove() with flags equal to PMEM_F_MEM_NODRAIN.

pmem_memcpy_nodrain() is an alias for pmem_memcpy() with flags equal to PMEM_F_MEM_NODRAIN.

pmem_memset_nodrain() is an alias for pmem_memset() with flags equal to PMEM_F_MEM_NODRAIN.

RETURN VALUE¶

CAVEATS¶

SEE ALSO¶