Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PMEMOBJ_MEMCPY_PERSIST(3)  PMDK	Programmer's Manual  PMEMOBJ_MEMCPY_PERSIST(3)

NAME
       pmemobj_persist(),    pmemobj_xpersist(),    pmemobj_flush(),	pmemo-
       bj_xflush(),  pmemobj_drain(),	pmemobj_memcpy(),   pmemobj_memmove(),
       pmemobj_memset(),  pmemobj_memcpy_persist(), pmemobj_memset_persist() -
       low-level memory	manipulation functions

SYNOPSIS
	      #include <libpmemobj.h>

	      void pmemobj_persist(PMEMobjpool *pop, const void	*addr,
		  size_t len);
	      void pmemobj_flush(PMEMobjpool *pop, const void *addr,
		  size_t len);
	      void pmemobj_drain(PMEMobjpool *pop);

	      int pmemobj_xpersist(PMEMobjpool *pop, const void	*addr,
		  size_t len, unsigned flags);
	      int pmemobj_xflush(PMEMobjpool *pop, const void *addr,
		  size_t len, unsigned flags);

	      void *pmemobj_memcpy(PMEMobjpool *pop, void *dest,
		  const	void *src, size_t len, unsigned	flags);
	      void *pmemobj_memmove(PMEMobjpool	*pop, void *dest,
		  const	void *src, size_t len, unsigned	flags);
	      void *pmemobj_memset(PMEMobjpool *pop, void *dest,
		  int c, size_t	len, unsigned flags);

	      void *pmemobj_memcpy_persist(PMEMobjpool *pop, void *dest,
		  const	void *src, size_t len);
	      void *pmemobj_memset_persist(PMEMobjpool *pop, void *dest,
		  int c, size_t	len);

DESCRIPTION
       The libpmemobj-specific low-level  memory  manipulation	functions  de-
       scribed here leverage the knowledge of the additional configuration op-
       tions available for libpmemobj(7) pools,	such as	replication.  They al-
       so take advantage of the	type of	storage	behind the pool	and use	appro-
       priate flush/drain functions.  It is advised to use these functions  in
       conjunction with	libpmemobj(7) objects rather than using	low-level mem-
       ory manipulation	functions from libpmem.

       pmemobj_persist() forces	any changes in the range [addr,	 addr+len)  to
       be  stored  durably in persistent memory.  Internally this may call ei-
       ther pmem_msync(3) or pmem_persist(3).  There are no alignment restric-
       tions on	the range described by addr and	len, but pmemobj_persist() may
       expand the range	as necessary to	meet platform alignment	requirements.

	      WARNING: Like msync(2), there is nothing atomic or transactional
	      about  this  call.  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	pmemo-
	      bj_persist()  is	called	to become persistent - they can	become
	      persistent at any	time before pmemobj_persist() is called.

       The pmemobj_flush() and pmemobj_drain() functions provide partial  ver-
       sions  of  the pmemobj_persist()	function described above.  These func-
       tions allow advanced programs to	create their own variations of	pmemo-
       bj_persist().   For example, a program that needs to flush several dis-
       contiguous ranges can call pmemobj_flush() for each range and then fol-
       low  up	by calling pmemobj_drain() once.  For more information on par-
       tial flushing operations, see pmem_flush(3).

       pmemobj_xpersist() is a version of pmemobj_persist() function with  ad-
       ditional	 flags argument.  It supports only the PMEMOBJ_F_RELAXED flag.
       This flag indicates that	memory transfer	 operation  does  not  require
       8-byte atomicity	guarantees.

       pmemobj_xflush()	 is  a	version	of pmemobj_flush() function with addi-
       tional flags argument.  It supports only	the PMEMOBJ_F_RELAXED flag.

       The pmemobj_memmove(), pmemobj_memcpy() and pmemobj_memset()  functions
       provide	the  same  memory  copying as their namesakes memmove(3), mem-
       cpy(3), and memset(3), and ensure that the result has been  flushed  to
       persistence  before  returning  (unless	PMEMOBJ_MEM_NOFLUSH  flag  was
       used).  Valid flags for those functions:

       o PMEMOBJ_F_RELAXED - This flag indicates that memory  transfer	opera-
	 tion does not require 8-byte atomicity	guarantees.

       o PMEMOBJ_F_MEM_NOFLUSH	-  Don't  flush	anything.  This	implies	PMEMO-
	 BJ_F_MEM_NODRAIN.  Using this flag only makes sense  when  it's  fol-
	 lowed by any function that flushes data.

       The remaining flags say how the operation should	be done, and are mere-
       ly hints.

       o PMEMOBJ_F_MEM_NONTEMPORAL - Use non-temporal instructions.  This flag
	 is  mutually  exclusive  with PMEMOBJ_F_MEM_TEMPORAL.	On x86_64 this
	 flag is mutually exclusive with PMEMOBJ_F_MEM_NOFLUSH.

       o PMEMOBJ_F_MEM_TEMPORAL	- Use temporal instructions.  This flag	is mu-
	 tually	exclusive with PMEMOBJ_F_MEM_NONTEMPORAL.

       o PMEMOBJ_F_MEM_WC  -  Use write	combining mode.	 This flag is mutually
	 exclusive with	PMEMOBJ_F_MEM_WB.  On x86_64  this  is	an  alias  for
	 PMEMOBJ_F_MEM_NONTEMPORAL.  On	x86_64 this flag is mutually exclusive
	 with PMEMOBJ_F_MEM_NOFLUSH.

       o PMEMOBJ_F_MEM_WB - Use	write back mode.  This flag is mutually	exclu-
	 sive  with  PMEMOBJ_F_MEM_WC.	 On x86_64 this	is an alias for	PMEMO-
	 BJ_F_MEM_TEMPORAL.

       pmemobj_memcpy_persist()	is an alias for	 pmemobj_memcpy()  with	 flags
       equal to	0.

       pmemobj_memset_persist()	 is  an	 alias for pmemobj_memset() with flags
       equal to	0.

RETURN VALUE
       pmemobj_memmove(),  pmemobj_memcpy(),  pmemobj_memset(),	  pmemobj_mem-
       cpy_persist() and pmemobj_memset_persist() return destination buffer.

       pmemobj_persist(),  pmemobj_flush()  and	 pmemobj_drain() do not	return
       any value.

       pmemobj_xpersist() and pmemobj_xflush() returns non-zero	value and sets
       errno to	EINVAL only if not supported flags has been provided.

EXAMPLES
       The  following  code  is	functionally equivalent	to pmemobj_memcpy_per-
       sist():

	      void *
	      pmemobj_memcpy_persist(PMEMobjpool *pop, void *dest,
		  const	void *src, size_t len)
	      {
		  void *retval = memcpy(dest, src, len);

		  pmemobj_persist(pop, dest, len);

		  return retval;
	      }

       pmemobj_persist() can be	thought	of as this:

	      void
	      pmemobj_persist(PMEMobjpool *pop,	const void *addr, size_t len)
	      {
		  /* flush the processor caches	*/
		  pmemobj_flush(pop, addr, len);

		  /* wait for any pmem stores to drain from HW buffers */
		  pmemobj_drain(pop);
	      }

SEE ALSO
       memcpy(3), memset(3), pmem_msync(3), pmem_persist(3), libpmem(7)	 libp-
       memobj(7) and <http://pmem.io>

PMDK - pmemobj API version 2.3	  2019-07-10	     PMEMOBJ_MEMCPY_PERSIST(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | EXAMPLES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pmemobj_memcpy_persist&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help