pmem API version 1.1

The PMDK repository on GitHub is the ultimate source of information on PMDK from release 2.0! For all questions and to submit eventual issues please follow to that repository. The PMDK documentation collected here should be valid up to the 1.13.1 release but is maintained only on a best-effort basis and may not reflect the latest state of the art.

comment: <> (SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT) comment: <> (LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,) comment: <> (DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY) comment: <> (THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT) comment: <> ((INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE) comment: <> (OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.)

comment: <> (pmem_memmove_persist.3 – man page for functions that provide optimized copying to persistent memory

NAME
SYNOPSIS
DESCRIPTION
RETURN VALUE
SEE ALSO

NAME

pmem_memmove_persist(), pmem_memcpy_persist(), pmem_memset_persist(), pmem_memmove_nodrain(), pmem_memcpy_nodrain(), pmem_memset_nodrain()

  • functions that provide optimized copying to persistent memory

SYNOPSIS

#include <libpmem.h>

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

The pmem_memmove_persist(), pmem_memcpy_persist(), and pmem_memset_persist(), functions provide the same memory copying as their namesakes memmove(3), memcpy(3) and memset(3), and ensure that the result has been flushed to persistence before returning. For example, the following code is functionally equivalent to pmem_memmove_persist():

void *
pmem_memmove_persist(void *pmemdest, const void *src, size_t len)
{
	void *retval = memmove(pmemdest, src, len);

	pmem_persist(pmemdest, len);

	return retval;
}

Calling pmem_memmove_persist() may out-perform the above code, however, since the 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.

WARNING: Using these functions where pmem_is_pmem(3) returns false may not do anything useful. Use the normal libc functions in that case.

The pmem_memmove_nodrain(), pmem_memcpy_nodrain() and pmem_memset_nodrain() functions are similar to pmem_memmove_persist(), pmem_memcpy_persist(), and pmem_memset_persist() described above, except they 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 these functions 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_nodrain(pmemdest1, src1, len1);
pmem_memcpy_nodrain(pmemdest2, src2, len2);

/* ... */

/* wait for any pmem stores to drain from HW buffers */
pmem_drain();

RETURN VALUE

The pmem_memmove_persist(), pmem_memcpy_persist(), pmem_memset_persist(), pmem_memmove_nodrain(), pmem_memcpy_nodrain() and pmem_memset_nodrain() functions return the address of the destination.

CAVEATS

After calling any of the _nodrain functions (pmem_memmove_nodrain(), pmem_memcpy_nodrain() or pmem_memset_nodrain()) you should not expect memory to be visible to other threads before calling pmem_drain(3) or any of the _persist functions. This is because those functions may use non-temporal store instructions, which are weakly ordered. See “Intel 64 and IA-32 Architectures Software Developer’s Manual”, Volume 1, “Caching of Temporal vs. Non-Temporal Data” section for details.

SEE ALSO

memcpy(3), memmove(3), memset(3), libpmem(7) and http://pmem.io

The contents of this web site and the associated GitHub repositories are BSD-licensed open source.