Primitives

Basic classes that provide PMEM-aware pointers and pool handlers. More...

Classes
class	pmem::obj::experimental::self_relative_ptr< T >
	Persistent self-relative pointer class. More...
class	pmem::obj::experimental::v< T >
	Volatile residing on pmem class. More...
class	pmem::obj::p< T >
	Resides on pmem class. More...
class	pmem::obj::persistent_ptr< T >
	Persistent pointer class. More...
class	pmem::obj::pool_base
	The non-template pool base class. More...
class	pmem::obj::pool< T >
	PMEMobj pool class. More...

Detailed Description

Basic classes that provide PMEM-aware pointers and pool handlers.

Pointers

There are few types to handle data on PMEM.

• pmem::obj::persistent_ptr<T> - implements a smart pointer. It encapsulates the PMEMoid fat pointer and provides member access, dereference and array access operators.
• pmem::obj::experimental::self_relative_ptr<T> - implements a smart ptr. It encapsulates the self-offsetted pointer and provides member access, dereference and array access operators. self_relative_ptr in comparison to persistent_ptr is:
  • smaller in size (8B vs 16B),
  • can be used with atomic operations,
  • dereferenced faster (it's important, e.g., in loops),
  • allows vectorization,
  • if stored in a persistent memory pool, it can only points to elements within the same pool.
• pmem::obj::p<T> - template class that can be used for all variables (except persistent pointers), which are used in Transactions. This class is not designed to be used with compound types. For that see the pmem::obj::persistent_ptr.
• pmem::obj::experimental::v<T> - property-like template class that has to be used for all volatile variables that reside on persistent memory. This class ensures that the enclosed type is always properly initialized by always calling the class default constructor exactly once per instance of the application. This class has 8 bytes of storage overhead.

Pool handles

Pool class provides basic operations on pmemobj pools. C++ API for pools should not be mixed with C API. For example explicitly calling pmemobj_set_user_data(pop) on pool which is handled by C++ pool object is undefined behaviour.

There are few pool handlers:

• pmem::obj::pool<T> - the template parameter defines the type of the root object within the pool. This pool class inherits also some methods from the base class: pmem::obj::pool_base. Example:

  #include <fcntl.h>
  #include <libpmemobj++/p.hpp>
  #include <libpmemobj++/persistent_ptr.hpp>
  #include <libpmemobj++/pool.hpp>
   
  using namespace pmem::obj;
   
  void
  pool_example()
  {
   
      /* pool root structure */
      struct root {
          p<int> some_array[42];
          p<int> some_other_array[42];
          p<double> some_variable;
      };
   
      /* create a pmemobj pool */
      auto pop = pool<root>::create("poolfile", "layout", PMEMOBJ_MIN_POOL);
   
      /* close a pmemobj pool */
      pop.close();
   
      /* or open a pmemobj pool */
      pop = pool<root>::open("poolfile", "layout");
   
      /* typical usage schemes */
      auto root_obj = pop.root();
   
      /* low-level memory manipulation */
      root_obj->some_variable = 3.2;
      pop.persist(root_obj->some_variable);
   
      pop.memset_persist(root_obj->some_array, 2,
                 sizeof(root_obj->some_array));
   
      pop.memcpy_persist(root_obj->some_other_array, root_obj->some_array,
                 sizeof(root_obj->some_array));
   
      pop.close();
   
      /* check pool consistency */
      pool<root>::check("poolfile", "layout");
  }

• pmem::obj::pool_base<T> - non template, basic version of pool, useful when specifying root type is not desirable. The typical usage example would be:

  #include <fcntl.h>
  #include <libpmemobj++/make_persistent_atomic.hpp>
  #include <libpmemobj++/p.hpp>
  #include <libpmemobj++/pool.hpp>
   
  using namespace pmem::obj;
   
  void
  pool_base_example()
  {
   
      struct some_struct {
          p<int> some_array[42];
          p<int> some_other_array[42];
          p<int> some_variable;
      };
   
      /* create a pmemobj pool */
      auto pop = pool_base::create("poolfile", "", PMEMOBJ_MIN_POOL);
   
      /* close a pmemobj pool */
      pop.close();
   
      /* or open a pmemobj pool */
      pop = pool_base::open("poolfile", "");
   
      /* no "root" object available in pool_base */
      persistent_ptr<some_struct> pval;
      make_persistent_atomic<some_struct>(pop, pval);
   
      /* low-level memory manipulation */
      pval->some_variable = 3;
      pop.persist(pval->some_variable);
   
      pop.memset_persist(pval->some_array, 2, sizeof(pval->some_array));
   
      pop.memcpy_persist(pval->some_other_array, pval->some_array,
                 sizeof(pval->some_array));
   
      pop.close();
   
      /* check pool consistency */
      pool_base::check("poolfile", "");
  }