Man page - pmem2_get_persist_fn(3)

Packages contains this manual

Package: libpmem2-dev
apt-get install libpmem2-dev

Manuals in package:

Documentations in package:

libpmem2-dev

Manual

NAME
SYNOPSIS
DESCRIPTION
RETURN VALUE
SEE ALSO

NAME

pmem2_get_persist_fn () - get a persist function

SYNOPSIS

#include <libpmem2.h>

typedef void (*pmem2_persist_fn)(const void *ptr, size_t size);

struct pmem2_map;


pmem2_persist_fn pmem2_get_persist_fn(struct pmem2_map *map);

DESCRIPTION

The pmem2_get_persist_fn () function returns a pointer to a function responsible for efficiently persisting data in the range owned by the map .

Persisting data using pmem2_persist_fn guarantees that the data is stored durably by the time it returns.

There are no alignment restrictions on the range described by ptr and size , but pmem2_persist_fn may expand the range as necessary to meet platform alignment requirements.

There is nothing atomic or transactional about pmem2_persist_fn . Any unwritten stores in the given range will be written, but some stores may have already been written by virtue of normal cache eviction/replacement policies. Correctly written code must not depend on stores waiting until pmem2_persist_fn is called to become persistent – they can become persistent at any time before pmem2_persist_fn is called.

If two (or more) mappings share the same pmem2_persist_fn and they are adjacent to each other, it is safe to call this function for a range spanning those mappings.

Internally pmem2_persist_fn performs two operations:

	•		memory flush ( pmem2_get_flush_fn (3)), which can be reordered by the CPU with other flushes
	•		drain ( pmem2_get_drain_fn (3)), which makes sure that the flushes before this operation won’t be reordered after it

So this code:

pmem2_persist_fn persist_fn = pmem2_get_persist_fn(map);
persist_fn(addr, len);

is equivalent of:

pmem2_flush_fn flush_fn = pmem2_get_flush_fn(map);
pmem2_drain_fn drain_fn = pmem2_get_drain_fn(map);

flush_fn(addr, len);
drain_fn();

Advanced applications may want to flush multiple discontiguous regions and perform the drain operation only once.

RETURN VALUE

The pmem2_get_persist_fn () function never returns NULL.

The pmem2_get_persist_fn () for the same map always returns the same function. This means that it’s safe to cache its return value. However, this function is very cheap (because it returns a precomputed value), so caching may not be necessary.