.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "" "" "2023-05-26" "PMDK - " "PMDK Programmer's Manual"
.hy
.\" SPDX-License-Identifier: BSD-3-Clause
.\" Copyright 2020, Intel Corporation
.SH NAME
.PP
\f[B]pmem2_get_persist_fn\f[R]() - get a persist function
.SH SYNOPSIS
.IP
.nf
\f[C]
#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);
\f[R]
.fi
.SH DESCRIPTION
.PP
The \f[B]pmem2_get_persist_fn\f[R]() function returns a pointer to a
function responsible for efficiently persisting data in the range owned
by the \f[I]map\f[R].
.PP
Persisting data using \f[I]pmem2_persist_fn\f[R] guarantees that the
data is stored durably by the time it returns.
.PP
There are no alignment restrictions on the range described by
\f[I]ptr\f[R] and \f[I]size\f[R], but \f[I]pmem2_persist_fn\f[R] may
expand the range as necessary to meet platform alignment requirements.
.PP
There is nothing atomic or transactional about
\f[I]pmem2_persist_fn\f[R].
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
\f[I]pmem2_persist_fn\f[R] is called to become persistent \[en] they can
become persistent at any time before \f[I]pmem2_persist_fn\f[R] is
called.
.PP
If two (or more) mappings share the same \f[I]pmem2_persist_fn\f[R] and
they are adjacent to each other, it is safe to call this function for a
range spanning those mappings.
.PP
Internally \f[I]pmem2_persist_fn\f[R] performs two operations:
.IP \[bu] 2
memory flush (\f[B]pmem2_get_flush_fn\f[R](3)), which can be reordered
by the CPU with other flushes
.IP \[bu] 2
drain (\f[B]pmem2_get_drain_fn\f[R](3)), which makes sure that the
flushes before this operation won\[cq]t be reordered after it
.PP
So this code:
.IP
.nf
\f[C]
pmem2_persist_fn persist_fn = pmem2_get_persist_fn(map);
persist_fn(addr, len);
\f[R]
.fi
.PP
is equivalent of:
.IP
.nf
\f[C]
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();
\f[R]
.fi
.PP
Advanced applications may want to flush multiple discontiguous regions
and perform the drain operation only once.
.SH RETURN VALUE
.PP
The \f[B]pmem2_get_persist_fn\f[R]() function never returns NULL.
.PP
The \f[B]pmem2_get_persist_fn\f[R]() for the same \f[I]map\f[R] always
returns the same function.
This means that it\[cq]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.
.SH SEE ALSO
.PP
\f[B]pmem2_get_drain_fn\f[R](3), \f[B]pmem2_get_flush_fn\f[R](3),
\f[B]pmem2_map_new\f[R](3), \f[B]libpmem2\f[R](7) and
\f[B]<https://pmem.io>\f[R]