NAME

       pmemobj_memcpy_persist(),  pmemobj_memset_persist(),  pmemobj_persist(),  pmemobj_flush(),
       pmemobj_drain() - low-level memory manipulation functions

SYNOPSIS

              #include <libpmemobj.h>

              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);
              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);

DESCRIPTION

       The libpmemobj-specific low-level memory manipulation functions  described  here  leverage
       the  knowledge  of the additional configuration options available for libpmemobj(7) pools,
       such as replication.  They also take advantage of the type of storage behind the pool  and
       use  appropriate  flush/drain  functions.   It  is  advised  to  use  these  functions  in
       conjunction with libpmemobj(7) objects rather than  using  low-level  memory  manipulation
       functions from libpmem.

       The  pmemobj_memcpy_persist()  and  pmemobj_memset_persist()  functions  provide  the same
       memory copying as their namesakes memcpy(3), and memset(3), and ensure that the result has
       been flushed to persistence before returning.

       pmemobj_persist() forces any changes in the range [addr, addr+len) to be stored durably in
       persistent memory.  Internally this may  call  either  pmem_msync(3)  or  pmem_persist(3).
       There  are  no  alignment  restrictions  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 pmemobj_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  versions  of  the
       pmemobj_persist()  function  described  above.  These functions allow advanced programs to
       create their own variations of pmemobj_persist().  For example, a program  that  needs  to
       flush several discontiguous ranges can call pmemobj_flush() for each range and then follow
       up by calling pmemobj_drain() once.  For more information on partial flushing  operations,
       see pmem_flush(3).

RETURN VALUE

       The pmemobj_memcpy_persist() and pmemobj_memset_persist() functions return the same values
       as their namesakes memcpy(3), and memset(3).

       pmemobj_persist(), pmemobj_flush() and pmemobj_drain() return no value.

EXAMPLES

       The following code is functionally equivalent to pmemobj_memcpy_persist():

              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)   libpmemobj(7)   and
       <http://pmem.io>