.\" Automatically generated by Pandoc 2.0.6
.\"
.TH "PMEM2_GET_PERSIST_FN" "3" "2022-08-25" "PMDK - pmem2 API version 1.0" "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[]() \- 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[]
.fi
.SH DESCRIPTION
.PP
The \f[B]pmem2_get_persist_fn\f[]() function returns a pointer to a
function responsible for efficiently persisting data in the range owned
by the \f[I]map\f[].
.PP
Persisting data using \f[I]pmem2_persist_fn\f[] 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[] and \f[I]size\f[], but \f[I]pmem2_persist_fn\f[] 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[].
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[] is called to become persistent \[en] they can
become persistent at any time before \f[I]pmem2_persist_fn\f[] is
called.
.PP
If two (or more) mappings share the same \f[I]pmem2_persist_fn\f[] 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[] performs two operations:
.IP \[bu] 2
memory flush (\f[B]pmem2_get_flush_fn\f[](3)), which can be reordered by
the CPU with other flushes
.IP \[bu] 2
drain (\f[B]pmem2_get_drain_fn\f[](3)), which makes sure that the
flushes before this operation won'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[]
.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[]
.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[]() function never returns NULL.
.PP
The \f[B]pmem2_get_persist_fn\f[]() for the same \f[I]map\f[] 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.
.SH SEE ALSO
.PP
\f[B]pmem2_get_drain_fn\f[](3), \f[B]pmem2_get_flush_fn\f[](3),
\f[B]pmem2_map_new\f[](3), \f[B]libpmem2\f[](7) and
\f[B]<https://pmem.io>\f[]