doc: extend docs for Allocation group and its functions

PersistentMemory · Oct 19, 2021 · 901eae9 · 901eae9
1 parent 4071057
commit 901eae9
Show file tree

Hide file tree

Showing 6 changed files with 75 additions and 19 deletions.
diff --git a/doc/groups_definitions.dox b/doc/groups_definitions.dox
@@ -159,7 +159,30 @@
   * - [blog post about transactional allocations](https://pmem.io/2016/05/19/cpp-06.html)
   */
 
-/** @defgroup allocation Allocation*/
+/** @defgroup allocation Allocation
+  * Functions and classes to support allocations on pmem
+  *
+  * Libpmemobj-cpp introduced special functions for allocating objects and arrays
+  * of objects on persistent memory, with ease. For all `make_persistent` specializations
+  * there are also `delete_persistent` counterparts. The latter are used to free memory
+  * of previously allocated objects or arrays, and calling their destructors. Each
+  * specialization comes in two versions - atomic and transactional. First one is
+  * distinguished with `_atomic` suffix (e.g. `make_persistent_atomic()`) and should not
+  * be called within an active transaction - it may lead to undefined behavior in case
+  * of transaction's rollback. On the other hand, transactional functions will throw
+  * an exception if called outside of an active transaction.
+  *
+  * For more flexibly approach we introduced pmem::obj::allocator class, which implements
+  * the concept of C++ Allocator. Allocation and deallocation using this class can only
+  * happen within an active transactions.
+  *
+  * The *typical use case* of data allocation on pmem would be:
+  * @snippet make_persistent/make_persistent.cpp make_example
+  *
+  * For allocator usage see pmem::obj::experimental::inline_string example:
+  * @snippet inline_string/inline_string.cpp inline_string_example
+  */
+
 /** @defgroup data_view Data View*/
 /** @defgroup synchronization Synchronization Primitives*/
 /** @defgroup primitives Primitives*/

diff --git a/include/libpmemobj++/allocator.hpp b/include/libpmemobj++/allocator.hpp
@@ -136,8 +136,9 @@ class object_traits {
 };
 
 /**
- * Object traits specialization for the void type. Designed to be used
- * with C++ allocators. Can be specialized if necessary.
+ * Object traits specialization for the void type.
+ *
+ * Designed to be used with C++ allocators. Can be specialized if necessary.
  * @ingroup allocation
  */
 template <>
@@ -179,8 +180,8 @@ class object_traits<void> {
 /**
  * The allocation policy template for a given type.
  *
- * Can be specialized for a given type. Designed to be used with C++ allocators.
- * Can be specialized if necessary.
+ * Can be specialized, if necessary, for a given type. Designed to be used
+ * with C++ allocators.
  * @ingroup allocation
  */
 template <typename T>
@@ -236,7 +237,8 @@ class standard_alloc_policy {
 	 *
 	 * @param[in] cnt the number of objects to allocate memory for.
 	 *
-	 * @throw transaction_scope_error if called outside of a transaction.
+	 * @throw transaction_scope_error if called outside of an active
+	 * transaction.
 	 * @throw transaction_out_of_memory if there is no free memory of
 	 * requested size.
 	 * @throw transaction_alloc_error on transactional allocation failure.
@@ -273,6 +275,10 @@ class standard_alloc_policy {
 	 * intervening call to deallocate.
 	 *
 	 * @param[in] p pointer to the memory to be deallocated.
+	 *
+	 * @throw transaction_scope_error if called outside of an active
+	 * transaction.
+	 * @throw transaction_free_error on transactional free failure.
 	 */
 	void
 	deallocate(pointer p, size_type = 0)
@@ -355,7 +361,11 @@ class standard_alloc_policy<void> {
 	 *
 	 * @param[in] cnt the number of bytes to be allocated.
 	 *
-	 * @throw transaction_scope_error if called outside of a transaction.
+	 * @throw transaction_scope_error if called outside of an active
+	 * transaction.
+	 * @throw transaction_out_of_memory if there is no free memory of
+	 * requested size.
+	 * @throw transaction_alloc_error on transactional allocation failure.
 	 */
 	pointer
 	allocate(size_type cnt, const_pointer = 0)
@@ -388,6 +398,10 @@ class standard_alloc_policy<void> {
 	 * intervening call to deallocate.
 	 *
 	 * @param[in] p pointer to the memory to be deallocated.
+	 *
+	 * @throw transaction_scope_error if called outside of an active
+	 * transaction.
+	 * @throw transaction_free_error on transactional free failure.
 	 */
 	void
 	deallocate(pointer p, size_type = 0)
@@ -446,6 +460,7 @@ operator==(standard_alloc_policy<T> const &, OtherAllocator const &)
  * the knowledge of the pointer type, their difference type, the type of the
  * size of objects in this allocation model as well as memory allocation and
  * deallocation primitives.
+ * @ingroup allocation
  */
 template <typename T, typename Policy = standard_alloc_policy<T>,
 	  typename Traits = object_traits<T>>

diff --git a/include/libpmemobj++/make_persistent.hpp b/include/libpmemobj++/make_persistent.hpp
@@ -3,8 +3,9 @@
 
 /**
  * @file
- * Persistent_ptr transactional allocation functions for objects. The typical
- * usage examples would be:
+ * persistent_ptr transactional allocation functions for objects.
+ *
+ * The typical usage examples would be:
  * @snippet make_persistent/make_persistent.cpp make_example
  */
 
@@ -42,6 +43,8 @@ namespace obj
  *
  * @throw transaction_scope_error if called outside of an active
  * transaction
+ * @throw transaction_out_of_memory if there is no free memory of
+ * requested size.
  * @throw transaction_alloc_error on transactional allocation failure.
  * @throw rethrow exception from T constructor
  * @ingroup allocation
@@ -84,6 +87,8 @@ make_persistent(allocation_flag flag, Args &&... args)
  *
  * @throw transaction_scope_error if called outside of an active
  * transaction
+ * @throw transaction_out_of_memory if there is no free memory of
+ * requested size.
  * @throw transaction_alloc_error on transactional allocation failure.
  * @throw rethrow exception from T constructor
  * @ingroup allocation

diff --git a/include/libpmemobj++/make_persistent_array.hpp b/include/libpmemobj++/make_persistent_array.hpp
@@ -3,8 +3,9 @@
 
 /**
  * @file
- * Persistent_ptr allocation functions for arrays. The typical usage examples
- * would be:
+ * persistent_ptr transactional allocation functions for arrays.
+ *
+ * The typical usage examples would be:
  * @snippet make_persistent/make_persistent.cpp make_array_example
  */
 
@@ -42,6 +43,8 @@ namespace obj
  *
  * @throw transaction_scope_error if called outside of an active
  * transaction
+ * @throw transaction_out_of_memory if there is no free memory of
+ * requested size.
  * @throw transaction_alloc_error on transactional allocation failure.
  * @throw rethrow exception from T constructor
  * @ingroup allocation
@@ -109,6 +112,8 @@ make_persistent(std::size_t N, allocation_flag flag = allocation_flag::none())
  *
  * @throw transaction_scope_error if called outside of an active
  * transaction
+ * @throw transaction_out_of_memory if there is no free memory of
+ * requested size.
  * @throw transaction_alloc_error on transactional allocation failure.
  * @throw rethrow exception from T constructor
  * @ingroup allocation
@@ -174,6 +179,7 @@ make_persistent(allocation_flag flag = allocation_flag::none())
  * @throw transaction_scope_error if called outside of an active
  * transaction
  * @throw transaction_free_error on transactional free failure.
+ * @ingroup allocation
  */
 template <typename T>
 void
@@ -220,6 +226,7 @@ delete_persistent(typename detail::pp_if_array<T>::type ptr, std::size_t N)
  * @throw transaction_scope_error if called outside of an active
  * transaction
  * @throw transaction_free_error on transactional free failure.
+ * @ingroup allocation
  */
 template <typename T>
 void

diff --git a/include/libpmemobj++/make_persistent_array_atomic.hpp b/include/libpmemobj++/make_persistent_array_atomic.hpp
@@ -1,10 +1,11 @@
 // SPDX-License-Identifier: BSD-3-Clause
-/* Copyright 2016-2020, Intel Corporation */
+/* Copyright 2016-2021, Intel Corporation */
 
 /**
  * @file
- * Atomic persistent_ptr allocation functions for arrays. The typical usage
- * examples would be:
+ * persistent_ptr atomic allocation functions for arrays.
+ *
+ * The typical usage examples would be:
  * @snippet make_persistent/make_persistent.cpp make_array_atomic_example
  */
 
@@ -40,6 +41,7 @@ namespace obj
  * @param[in] flag affects behaviour of allocator
  *
  * @throw std::bad_alloc on allocation failure.
+ * @ingroup allocation
  */
 template <typename T>
 void
@@ -72,6 +74,7 @@ make_persistent_atomic(
  * @param[in] flag affects behaviour of allocator
  *
  * @throw std::bad_alloc on allocation failure.
+ * @ingroup allocation
  */
 template <typename T>
 void
@@ -98,8 +101,9 @@ make_persistent_atomic(
  * cleanup must be performed elsewhere. Do *NOT* use this inside transactions,
  * as it might lead to undefined behavior in the presence of transaction aborts.
  *
- * param[in,out] ptr the persistent_ptr whose pointee is to be
+ * @param[in,out] ptr the persistent_ptr whose pointee is to be
  * deallocated.
+ * @ingroup allocation
  */
 template <typename T>
 void
@@ -120,7 +124,8 @@ delete_persistent_atomic(typename detail::pp_if_array<T>::type &ptr,
  * cleanup must be performed elsewhere. Do *NOT* use this inside transactions,
  * as it might lead to undefined behavior in the presence of transaction aborts.
  *
- * param[in,out] ptr the persistent_ptr whose pointee is to be deallocated.
+ * @param[in,out] ptr the persistent_ptr whose pointee is to be deallocated.
+ * @ingroup allocation
  */
 template <typename T>
 void

diff --git a/include/libpmemobj++/make_persistent_atomic.hpp b/include/libpmemobj++/make_persistent_atomic.hpp
@@ -3,8 +3,9 @@
 
 /**
  * @file
- * Persistent_ptr atomic allocation functions for objects. The typical usage
- * examples would be:
+ * persistent_ptr atomic allocation functions for objects.
+ *
+ * The typical usage examples would be:
  * @snippet make_persistent/make_persistent.cpp make_atomic_example
  */
 
@@ -97,7 +98,7 @@ make_persistent_atomic(pool_base &pool,
  * cleanup must be performed elsewhere.  Do *NOT* use this inside transactions,
  * as it might lead to undefined behavior in the presence of transaction aborts.
  *
- * param[in,out] ptr the persistent_ptr whose pointee is to be
+ * @param[in,out] ptr the persistent_ptr whose pointee is to be
  * deallocated.
  * @ingroup allocation
  */