pmem2_get_memmove_fn - Man Page

get a function that provides optimized copying to persistent memory

Synopsis

#include <libpmem2.h>

typedef void *(*pmem2_memmove_fn)(void *pmemdest, const void *src, size_t len,
        unsigned flags);
typedef void *(*pmem2_memcpy_fn)(void *pmemdest, const void *src, size_t len,
        unsigned flags);
typedef void *(*pmem2_memset_fn)(void *pmemdest, int c, size_t len,
        unsigned flags);

struct pmem2_map;

pmem2_memmove_fn pmem2_get_memmove_fn(struct pmem2_map *map);
pmem2_memset_fn pmem2_get_memset_fn(struct pmem2_map *map);
pmem2_memcpy_fn pmem2_get_memcpy_fn(struct pmem2_map *map);

Description

The pmem2_get_memmove_fn(), pmem2_get_memset_fn(), pmem2_get_memcpy_fn() functions return a pointer to a function responsible for efficient storing and flushing of data for mapping map.

pmem2_memmove_fn(), pmem2_memset_fn() and pmem2_memcpy_fn() functions provide the same memory copying functionalities as their namesakes memmove(3), memcpy(3) and memset(3), and ensure that the result has been flushed to persistence before returning (unless PMEM2_F_MEM_NOFLUSH flag was used).

For example, the following code:

        memmove(dest, src, len);
        pmem2_persist_fn persist_fn = pmem2_get_persist_fn(map);
        persist_fn(dest, len);

is functionally equivalent to:

        pmem2_memmove_fn memmove_fn = pmem2_get_memmove_fn(map);
        memmove_fn(dest, src, len, 0);

Unlike libc implementation, libpmem2 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 persist_fn can be safely replaced by a single memmove_fn call.

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:

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

Using an invalid combination of flags has undefined behavior.

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

Return Value

The pmem2_get_memmove_fn(), pmem2_get_memset_fn(), pmem2_get_memcpy_fn() functions never return NULL.

They return the same function for the same mapping.

This means that it’s safe to cache their return values. However, these functions are very cheap (because their return values are precomputed), so caching may not be necessary.

If two (or more) mappings share the same pmem2_memmove_fn, pmem2_memset_fn, pmem2_memcpy_fn and they are adjacent to each other, it is safe to call these functions for a range spanning those mappings.

See Also

memcpy(3), memmove(3), memset(3), pmem2_get_drain_fn(3), pmem2_get_memcpy_fn(3), pmem2_get_memset_fn(3), pmem2_map_new(3), pmem2_get_persist_fn(3), libpmem2(7) and <http://pmem.io>

Referenced By

libpmem2(7).

The man pages pmem2_get_memcpy_fn(3) and pmem2_get_memset_fn(3) are aliases of pmem2_get_memmove_fn(3).

2020-10-28 PMDK - pmem2 API version 1.0 PMDK Programmer's Manual