Merge pull request #1201 from lukaszstolarczuk/expand-containers-docs

docs: update and extend containers information

Author: igchor

CONTRIBUTING.md

@@ -36,7 +36,7 @@ make cppformat
 ## Doxygen documentation
 
 * Each new feature should be documented using doxygen comment blocks.
-* Each non-member function should be added to corresponding class documentation by `@relates` tag
+* Each non-member function should be added to corresponding class documentation by `@relates` tag.
 * Each new API should be assigned to group by `@ingroup` tag. See [groups definitions file](doc/groups_definitions.dox) in the repository for details.
 
 # Submitting Pull Requests
@@ -95,25 +95,29 @@ Author: Random J Developer <[email protected]>
 When developing a persistent container make sure you follow the rules and steps described here.
 
 ## Steps
-1. Create container implementation
-2. Create doc_snippet/example
-3. Add TEST_CONTAINER CMake option for enabling/disabling container's testing.
-4. Add tests (+ if possible, enable libcxx tests in tests/external/libcxx)
 
-## Requirements:
+1. Create container implementation.
+2. Create doc_snippet(s) and example(s).
+3. Add `TEST_<CONTAINER>` CMake option for enabling/disabling container's testing.
+4. Add tests (including, if possible, adding new/enabling existing libcxx tests in `tests/external/libcxx`).
+
+## Requirements
+
 * Constructors should check whether the container is being constructed on pmem and within a transaction.
   If not, appropriate exception should be thrown.
 * If any operation has to or is not allowed to be called inside of a transaction there should be a proper check for that.
-* Operations which modify the entire container (like operator=, clear(), etc.) should be transactional.
-* If any operation inside destructor can fail there should be a separate method like free_data/destroy.
-* Each complex container should have a mechanism for checking layout compatibility. One way is to store size of key and value on pmem and compare it with sizeof(value_type) after pool reopen.
+* Operations which modify the entire container (like `operator=`, `clear()`, etc.) should be transactional.
+* If any operation inside destructor can fail there should be a separate method like `free_data` or `destroy`.
+* Each complex container should have a mechanism for checking layout compatibility.
+  One way is to store size of key and value on pmem and compare it with `sizeof(value_type)` after pool reopen.
 * Padding should always be explicit.
-* If any object from standard library is being stored on pmem its size should be verified by static_assert.
+* If any object from the standard library is being stored on pmem, its size should be verified by `static_assert`.
 * Public methods should be documented using doxygen comments.
 
-## Optional features:
-* for_each_ptr method for defragmentation purposes.
-* Containers with lower memory overhead (like vector) can implement some heuristic for verifying layout (like comparing pmemobj_alloc_usable_size with expected capacity).
+## Optional features
+
+* `for_each_ptr` method for defragmentation purposes.
+* Containers with lower memory overhead (like vector) can implement some heuristic for verifying layout (like comparing `pmemobj_alloc_usable_size` with expected capacity).
 
 # Configuring GitHub fork
 

doc/groups_definitions.dox

@@ -1,8 +1,74 @@
 # SPDX-License-Identifier: BSD-3-Clause
 # Copyright 2021, Intel Corporation
 
-/** @defgroup containers  Containers*/
-/** @defgroup experimental_containers Experimental Containers */
+/** @defgroup containers Containers
+  * 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 @ref 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 @ref 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](https://pmem.io/2018/11/20/cpp-persistent-containers.html)
+  * - [A blog post about array container](https://pmem.io/2018/11/02/cpp-array.html)
+  * - [Very first description of (then yet experimental) vector container](https://pmem.io/2019/02/20/cpp-vector.html)
+  *
+  * 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](https://pmem.io/2017/07/10/cpp-containers.html).
+  * The repo with that code is now dead, but left for the reference and historical perspective.
+  */
+
+/** @defgroup experimental_containers Experimental Containers
+  * PMem containers under development and/or in testing.
+  *
+  * It's very important to underline:
+  * @note **Experimental API may change (with no backward compatibility)
+  * and it should not be used in a production environment**
+  *
+  * A container is considered **experimental** because:
+  * - it may not be a 100% functionally ready,
+  * - tests are not finished and there might be some gaps/corner cases to be discovered and fixed,
+  * - we may still tweak the API (if we find it's not well defined),
+  * - its layout may change.
+  *
+  * For general containers' description please see @ref containers.
+  */
 
 /** @defgroup transactions Transactions
   * This section introduces transaction feature in libpmemobj-cpp.

include/libpmemobj++/README.md

@@ -105,39 +105,17 @@ Be aware that the old behavior can lead to segfaults in some cases
 
 # Persistent 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.
-
-## Available containers
-
- * array with STL-like interface - [pmem::obj::array](@ref pmem::obj::array)
- * string with STL-like interface - [pmem::obj::string](@ref pmem::obj::basic_string)
- * vector with STL-like interface - [pmem::obj::vector](@ref pmem::obj::vector)
- * segment_vector with std::vector-like interface (no STL counterpart) -
-    [pmem::obj::segment_vector](@ref pmem::obj::segment_vector)
- * concurrent_hash_map (no STL counterpart) -
-    [pmem::obj::concurrent_hash_map](@ref pmem::obj::concurrent_hash_map)
- * radix_tree (partially compatible with std::map) -
-    [pmem::obj::experimental::radix_tree](@ref pmem::obj::experimental::radix_tree)
- * concurrent_map (partially compatible with std::map) -
-    [pmem::obj::experimental::concurrent_map](@ref pmem::obj::experimental::concurrent_map)
+Persistent containers are implemented-from-scratch with optimized on-media layouts
+and algorithms to fully exploit the potential and features of persistent memory.
+Methods implemented within containers guarantee atomicity, consistency and durability.
+Besides specific internal implementation details, libpmemobj-cpp persistent memory containers
+have the well-known STL-like interfaces and they work with STL algorithms.
+
+For more information and a complete list of available containers
+(including experimental containers and specializations) see @ref containers.
+
+<!--
+If you're reading this in a markdown readme file you can found
+Containers Feature description in our Doxygen documentation online:
+https://pmem.io/libpmemobj-cpp/master/doxygen/group__containers.html
+-->

include/libpmemobj++/container/array.hpp

@@ -29,7 +29,7 @@ namespace obj
 {
 
 /**
- * pmem::obj::array - persistent container with std::array compatible interface.
+ * Persistent container with std::array compatible interface.
  *
  * pmem::obj::array can only be stored on pmem. Creating array on
  * stack will result with "pool_error" exception.
@@ -132,7 +132,7 @@ struct array {
 	 * Copy assignment operator - perform assignment from other
 	 * pmem::obj::array.
 	 *
-	 * This function creates a transaction internally.
+	 * This function internally creates a transaction.
 	 *
 	 * @throw transaction_error when adding the object to the
 	 *		transaction failed.
@@ -163,7 +163,7 @@ struct array {
 	 * Move assignment operator - perform move assignment from other
 	 * pmem::obj::array.
 	 *
-	 * This function creates a transaction internally.
+	 * This function internally creates a transaction.
 	 *
 	 * @throw transaction_error when adding the object to the
 	 *		transaction failed.

include/libpmemobj++/container/basic_string.hpp

@@ -34,12 +34,13 @@ namespace obj
 {
 
 /**
- * pmem::obj::string - persistent container with std::basic_string compatible
+ * Persistent string container with std::basic_string compatible
  * interface.
  *
- * The implementation is still missing some methods.
+ * The implementation is still missing some methods, but it doesn't
+ * impact regular use of this container.
  *
- * Simple example of pmem::obj::string usage
+ * Simple example of pmem::obj::string usage:
  * @snippet string/string.cpp string_example
  * @ingroup containers
  */

include/libpmemobj++/container/concurrent_hash_map.hpp

@@ -222,7 +222,7 @@ class scoped_lock_traits<ScopedLockType, false> {
 		return false;
 	}
 };
-}
+} /* namespace concurrent_hash_map_internal */
 
 template <typename Key, typename T, typename Hash = std::hash<Key>,
 	  typename KeyEqual = std::equal_to<Key>,
@@ -1375,7 +1375,7 @@ class hash_map_base {
 }; /* End of class hash_map_base */
 
 /**
- * Meets requirements of a forward iterator for STL
+ * Meets requirements of a forward iterator for STL.
  * Value is either the T or const T type of the container.
  * @ingroup containers
  */
@@ -1572,7 +1572,9 @@ operator!=(const hash_map_iterator<Container, M> &i,
 /** @endcond */
 
 /**
- * Persistent memory aware implementation of Intel TBB concurrent_hash_map.
+ * Persistent memory aware implementation of Intel TBB
+ * [concurrent_hash_map](https://spec.oneapi.io/versions/0.5.0/oneTBB/containers/concurrent_hash_map_cls.html)
+ *
  * The implementation is based on a concurrent hash table algorithm
  * (https://arxiv.org/ftp/arxiv/papers/1509/1509.02235.pdf) where elements
  * are assigned to buckets based on a hash code calculated from a key.
@@ -1581,6 +1583,9 @@ operator!=(const hash_map_iterator<Container, M> &i,
  * of an array of buckets, and each bucket consists of a list of nodes and a
  * read-write lock to control concurrent access by multiple threads.
  *
+ * There's no STL counterpart for this container (only the TBB's
+ * implementation).
+ *
  * Each time, the pool with concurrent_hash_map is being opened, the
  * concurrent_hash_map requires runtime_initialize() to be called (in order to
  * recalculate mask and restore the size).
@@ -1609,10 +1614,9 @@ operator!=(const hash_map_iterator<Container, M> &i,
  * improve performance if MutexType supports efficient upgrading and
  * downgrading operations.
  *
- * Testing note:
- * In some case, helgrind and drd might report lock ordering errors for
- * concurrent_hash_map. This might happen when calling find, insert or erase
- * while already holding an accessor to some element.
+ * @note In some cases, when testing with Valgrind, helgrind and drd might
+ * report lock ordering errors. This might happen when calling find, insert or
+ * erase while already holding an accessor to some element.
  *
  * The typical usage example would be:
  * @snippet concurrent_hash_map/concurrent_hash_map.cpp concurrent_hash_map_ex

include/libpmemobj++/container/segment_vector.hpp

@@ -484,7 +484,8 @@ using exponential_size_vector_policy =
 							 SegmentType>;
 
 /**
- * A persistent version of segment vector implementation.
+ * Persistent version of segment vector with std::vector compatible
+ * interface.
  *
  * Segment table is a data type with a vector-like interface. Differences
  * are: it does not do reallocations and iterators are not invalidated

include/libpmemobj++/container/string.hpp

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: BSD-3-Clause
-/* Copyright 2019, Intel Corporation */
+/* Copyright 2019-2021, Intel Corporation */
 
 /**
  * @file
@@ -17,9 +17,28 @@ namespace pmem
 namespace obj
 {
 
+/**
+ * The most typical string usage - the char specialization.
+ * @ingroup containers
+ */
 using string = basic_string<char>;
+
+/**
+ * The wide char specialization.
+ * @ingroup containers
+ */
 using wstring = basic_string<wchar_t>;
+
+/**
+ * The char16 specialization.
+ * @ingroup containers
+ */
 using u16string = basic_string<char16_t>;
+
+/**
+ * The char32 specialization.
+ * @ingroup containers
+ */
 using u32string = basic_string<char32_t>;
 
 } /* namespace obj */

include/libpmemobj++/container/vector.hpp

@@ -34,8 +34,7 @@ namespace obj
 {
 
 /**
- * pmem::obj::vector - persistent container with std::vector compatible
- * interface.
+ * Persistent container with std::vector compatible interface.
  * @ingroup containers
  */
 template <typename T>

include/libpmemobj++/detail/ebr.hpp

@@ -29,7 +29,7 @@
 
 /**
  * @file
- * C++ EBR API.
+ * C++ Epoch-based reclamation API.
  */
 
 #ifndef LIBPMEMOBJ_EBR_HPP
@@ -51,13 +51,7 @@ namespace detail
 {
 
 /**
- * Epoch-based reclamation (EBR). Reference:
- *
- *	K. Fraser, Practical lock-freedom,
- *	Technical Report UCAM-CL-TR-579, February 2004
- *	https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-579.pdf
- *
- * Summary:
+ * Epoch-based reclamation (EBR).
  *
  * Any workers (threads or processes) actively referencing (accessing)
  * the globally visible objects must do that in the critical path covered
@@ -66,7 +60,10 @@ namespace detail
  * each epoch). Objects in the current global epoch can be staged for
  * reclamation (garbage collection). Then, the objects in the target epoch can
  * be reclaimed after two successful increments of the global epoch. Only three
- * epochs are needed (e, e-1 and e-2), therefore we use clock arithmetics.
+ * epochs are needed (e, e-1 and e-2), therefore we use clock arithmetic.
+ *
+ * \see [K. Fraser, Practical lock-freedom, Technical Report UCAM-CL-TR-579,
+ * February 2004](https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-579.pdf)
  */
 class ebr {
 	using atomic = std::atomic<size_t>;