Merge pull request #1220 from lukaszstolarczuk/extend-allocation-feature-docs

Extend allocation feature docs

Author: lukaszstolarczuk

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*/

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

include/libpmemobj++/container/segment_vector.hpp

@@ -2553,8 +2553,8 @@ segment_vector<T, Policy>::construct_range(size_type idx, InputIt first,
  * gap for count elements starting at index idx. If there is not enough
  * space available, reallocation occurs.
  *
- * param[in] idx index number where gap should be made.
- * param[in] count length (expressed in number of elements) of the gap.
+ * @param[in] idx index number where gap should be made.
+ * @param[in] count length (expressed in number of elements) of the gap.
  *
  * @pre must be called in transaction scope.
  *

include/libpmemobj++/container/vector.hpp

@@ -2269,9 +2269,9 @@ vector<T>::construct_or_assign(size_type idx, InputIt first, InputIt last)
  * reallocation occurs with new recommended size. Range specified by first, last
  * is then inserted into the gap.
  *
- * param[in] idx index number where insert should be made
- * param[in] first iterator to beginning of the range to insert
- * param[in] last iterator to end of the range to insert
+ * @param[in] idx index number where insert should be made
+ * @param[in] first iterator to beginning of the range to insert
+ * @param[in] last iterator to end of the range to insert
  *
  * @pre must be called in transaction scope.
  *
@@ -2355,7 +2355,7 @@ vector<T>::internal_insert(size_type idx, InputIt first, InputIt last)
  * container is reduced to its first capacity_new elements. If was never
  * allocated behaves as an alloc call.
  *
- * param[in] capacity_new new capacity.
+ * @param[in] capacity_new new capacity.
  *
  * @pre must be called in transaction scope.
  *

include/libpmemobj++/experimental/inline_string.hpp

@@ -214,14 +214,48 @@ class basic_inline_string : public basic_inline_string_base<CharT, Traits> {
 	}
 };
 
+/**
+ * The most typical dram_inline_string usage - the char specialization.
+ * See basic_dram_inline_string for details.
+ * @ingroup experimental_containers
+ */
 using dram_inline_string = basic_dram_inline_string<char>;
+/**
+ * The wide char specialization.
+ * @ingroup experimental_containers
+ */
 using dram_inline_wstring = basic_dram_inline_string<wchar_t>;
+/**
+ * The char16 specialization.
+ * @ingroup experimental_containers
+ */
 using dram_inline_u16string = basic_dram_inline_string<char16_t>;
+/**
+ * The char32 specialization.
+ * @ingroup experimental_containers
+ */
 using dram_inline_u32string = basic_dram_inline_string<char32_t>;
 
+/**
+ * The most typical inline_string usage - the char specialization.
+ * See basic_inline_string for details.
+ * @ingroup experimental_containers
+ */
 using inline_string = basic_inline_string<char>;
+/**
+ * The wide char specialization.
+ * @ingroup experimental_containers
+ */
 using inline_wstring = basic_inline_string<wchar_t>;
+/**
+ * The char16 specialization.
+ * @ingroup experimental_containers
+ */
 using inline_u16string = basic_inline_string<char16_t>;
+/**
+ * The char32 specialization.
+ * @ingroup experimental_containers
+ */
 using inline_u32string = basic_inline_string<char32_t>;
 
 /**

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

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

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

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
  */