Containers

Custom (but STL-like) containers for persistent memory. More...

Classes
struct	pmem::obj::array< T, N >
	Persistent container with std::array compatible interface. More...
class	pmem::obj::basic_string< CharT, Traits >
	Persistent string container with std::basic_string compatible interface. More...
class	pmem::obj::concurrent_hash_map< Key, T, Hash, KeyEqual, MutexType, ScopedLockType >
	Persistent memory aware implementation of Intel TBB concurrent_hash_map More...
class	pmem::obj::segment_vector< T, Policy >
	Persistent version of segment vector with std::vector compatible interface. More...
class	pmem::obj::vector< T >
	Persistent container with std::vector compatible interface. More...

Typedefs
using	pmem::obj::string = basic_string< char >
	The most typical string usage - the char specialization.
using	pmem::obj::wstring = basic_string< wchar_t >
	The wide char specialization.
using	pmem::obj::u16string = basic_string< char16_t >
	The char16 specialization.
using	pmem::obj::u32string = basic_string< char32_t >
	The char32 specialization.

Detailed Description

Custom (but STL-like) containers for persistent memory.

Persistent containers are implemented-from-scratch with optimized on-media layouts and algorithms to fully exploit the potential and features of persistent memory. Besides specific internal implementation details, libpmemobj-cpp persistent memory containers have (where possible) the well-known STL-like interface and they work with STL algorithms. Containers' methods guarantee atomicity, consistency and durability. Note that every single modifier method (any one modifying the state of the container, like resize or push_back) opens transaction internally and guarantees full exception safety (modifications will be either committed or rolled-back if an exception was thrown, or crash happened - for more info see Transactions). There is no need for using transaction when calling modifier methods whatsoever.

There is a separate Feature describing and listing all experimental containers, see Experimental Containers.

Rationale for implementing pmem-aware containers

The C++ standard library containers collection is something that persistent memory programmers may want to use. Containers manage the lifetime of held objects through allocation/creation and deallocation/destruction with the use of allocators. Implementing custom persistent allocator for C++ STL (Standard Template Library) containers has two main downsides:

Implementation details:

• STL containers do not use algorithms optimal from persistent memory programming point of view.
• Persistent memory containers should have durability and consistency properties, while not every STL method guarantees strong exception safety.
• Persistent memory containers should be designed with an awareness of fragmentation limitations.

Memory layout:

• The STL does not guarantee that the container layout will remain unchanged in new library versions.

Due to these obstacles, the libpmemobj-cpp contains the set of custom, implemented-from-scratch containers with optimized on-media layouts and algorithms to fully exploit the potential and features of persistent memory. These methods guarantee atomicity, consistency and durability. Besides specific internal implementation details, libpmemobj-cpp persistent memory containers have the well-known STL-like interface and they work with STL algorithms.

Additional resources

• Blog post on pmem.io about libpmemobj-cpp persistent containers
• A blog post about array container
• Very first description of (then yet experimental) vector container

For curious readers - back then in 2017 - there was an approach to re-use and modify the STL containers to be pmem-aware. Story of implementing this experiment can be found in the blog post on pmem.io. The repo with that code is now dead, but left for the reference and historical perspective.