Merge pull request #1242 from lukaszstolarczuk/docs-update

Docs update

Author: lukaszstolarczuk

CONTRIBUTING.md

@@ -47,6 +47,13 @@ We take outside code contributions to `libpmemobj-cpp` through GitHub pull reque
 If you add a new feature or fix a critical bug please append appropriate entry
 to ChangeLog under newest release.
 
+## Choosing the correct branch
+
+Development of new features is done on `master` branch. High priority bug fixes are done on
+the oldest relevant `stable-*` branch and merged through newer stable branches up to the `master`.
+
+## Licence and Developer's Certificate of Origin
+
 **NOTE: If you do decide to implement code changes and contribute them,
 please make sure you agree your contribution can be made available under the
 [BSD-style License used for libpmemobj-cpp](LICENSE).**

doc/groups_definitions.dox

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: BSD-3-Clause
-# Copyright 2021, Intel Corporation
+# Copyright 2021-2022, Intel Corporation
 
 /** @defgroup containers Containers
   * Custom (but STL-like) containers for persistent memory.
@@ -18,7 +18,7 @@
   * There is a separate Feature describing and listing all
   * experimental containers, see @ref experimental_containers.
   *
-  * # Rationale for implementing pmem-aware 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
@@ -43,7 +43,7 @@
   * internal implementation details, libpmemobj-cpp persistent memory containers
   * have the well-known STL-like interface and they work with STL algorithms.
   *
-  * # Additional resources
+  * ## 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)
@@ -73,7 +73,7 @@
 /** @defgroup transactions Transactions
   * Transactional approach to store data on pmem.
   *
-  * # General info about transactions
+  * ## General info about transactions
   *
   * The heart of the libpmemobj are transactions. A transaction is defined as series of operations on
   * **persistent memory objects** that either all occur, or nothing occurs. In particular, if the execution
@@ -106,9 +106,6 @@
   * All operations between creating and destroying the transaction
   * object are treated as performed in a transaction block and
   * can be rolled back.
-  * The locks are held for the entire duration of the transaction. They
-  * are released at the end of the scope, so within the `catch` block,
-  * they are already unlocked.
   * The best way to use manual transactions is by
   * @ref pmem::obj::transaction::run, which is used in example above.
   *
@@ -117,14 +114,15 @@
   * performed in a transaction block and can be rolled back.
   * If you have a C++17 compliant compiler, the automatic transaction will
   * commit and abort automatically depending on the context of object's destruction.
-  * The locks are held for the entire duration of the transaction. They
-  * are released at the end of the scope, so within the `catch` block,
+  *
+  * In both approaches one of the parameters is the `locks`. They are held for the entire duration
+  * of the transaction and they are released at the end of the scope - so within the `catch` block,
   * they are already unlocked.
   *
   * If you want to read more and see example usages of both, you have to see
   * flat or basic transaction documentation, because each implementation may differ.
   *
-  * # Lifecycle and stages:
+  * ## Lifecycle and stages:
   *
   * When you are using transaction API a transaction can be in one of the following states:
   * - *TX_STAGE_NONE* - no open transaction in this thread
@@ -137,14 +135,14 @@
   * in libpmemobj-cpp it's transparent for user, so please focus on relationships between stages.
   * Look at the diagram below:
   *
-  * ![lifecycle](https://pmem.io/assets/lifecycle.png "Transaction lifecycle")
+  * ![lifecycle](https://pmem.io/images/posts/lifecycle.png "Transaction lifecycle")
   *
   * To be more familiar with functions used in diagram read e.g. **pmemobj_tx_begin**(3) manpage
   * (C API for [libpmemobj](https://pmem.io/pmdk/libpmemobj/), link below in *Additional resources*).
   *
   * If you need to read general information about transaction move to the *Additional resources* section.
   *
-  * # Example of flat_transaction
+  * ## Example of flat_transaction
   * For comparison with the previous snippet, here is a code snippet of
   * @ref pmem::obj::flat_transaction which is listed below with basic explanation inline.
   * @snippet transaction/transaction.cpp tx_nested_struct_example
@@ -153,7 +151,7 @@
   * For more examples please look at the
   * [examples directory](https://github.com/pmem/libpmemobj-cpp/tree/master/examples) in libpmemobj-cpp repository.
   *
-  * # Additional resources
+  * ## Additional resources
   * - [pmemobj_tx_begin(3) manpage with transaction description (C API)](https://pmem.io/pmdk/manpages/linux/master/libpmemobj/pmemobj_tx_begin.3)
   * - [blog post about transactions](https://pmem.io/2016/05/25/cpp-07.html)
   * - [blog post about transactional allocations](https://pmem.io/2016/05/19/cpp-06.html)
@@ -191,22 +189,40 @@
   * take a look at description of each class to get the details of their behavior.
   */
 
-/** @defgroup synchronization Synchronization Primitives*/
+/** @defgroup synchronization Synchronization Primitives
+  * Persistent memory resident implementation of synchronization primitives.
+  *
+  * In concurrent programming, we often require mechanisms for synchronizing access to shared resources.
+  * Typically to solve such issues we use synchronization primitives like mutexes and condition variables.
+  * As persistent memory offers bigger capacity than DRAM it may be useful to store synchronization primitives
+  * on it. Unfortunately such approach may cause performance degradation due to frequent writes to a memory
+  * with relatively higher latency (it's because taking a lock or signaling a conditional variable often
+  * requires additional writes). Few extra words how locks can be used in libpmemobj-cpp can be found in
+  * @ref transactions.
+  *
+  * It's worth noticing that pmem locks are automatically released on recovery or when crash happened.
+  *
+  * ## Additional resources
+  * - [Libpmemobj-cpp - lessons learned](https://pmem.io/blog/2021/09/libpmemobj-cpp-lessons-learned)
+  *   In this blog post we explain, i.a., why keeping locks on pmem is not a good idea.
+  */
+
 /** @defgroup primitives Primitives
-  * Basic classes that provides PMEM-aware pointers and pool handlers.
+  * Basic classes that provide PMEM-aware pointers and pool handlers.
   *
   * ## Pointers
   * There are few types to handle data on PMEM.
   * - @ref pmem::obj::persistent_ptr<T> - implements a smart pointer.
   * It encapsulates the [PMEMoid](https://pmem.io/2015/06/11/type-safety-macros.html) fat
   * pointer and provides member access, dereference and array access operators.
   * - @ref 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.
+  * 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 size (8B vs 16B)
-  *   - can be used with atomic operations
-  *   - faster dereference (important in loop), also allows vectorization
-  *   - if stored in a persistent memory pool, it can only points to elements within the same pool
+  *   - 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.
   * - @ref pmem::obj::p<T> - template class that can be used for all variables (except persistent pointers),
   * which are used in @ref transactions.
   * This class is not designed to be used with compound types. For that see the @ref pmem::obj::persistent_ptr.
@@ -216,8 +232,8 @@
   * 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](https://pmem.io/2016/05/10/cpp-05.html). C++ API for pools should
-  * not be mixed with C API. For example explicitly calling pmemobj_set_user_data(pop)
+  * Pool class provides basic operations on pmemobj [pools](https://pmem.io/2016/05/10/cpp-05.html).
+  * 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:
@@ -234,9 +250,10 @@
   * Possible exceptions that could be thrown by the libpmemobj++.
   *
   * In runtime, some operations may fail, then all you need is to catch the exception.
-  * Every pmem exception has **std::runtime_error** in its inheritance tree
-  * and contains proper message with an error description.
-  * All exceptions can be caught using just **std::runtime_error**.
+  * Every pmem exception has `std::runtime_error` in its inheritance tree, which means
+  * that all exceptions can be caught using just this type. Each exception contains
+  * proper message with an error description.
+  *
   * Look at the list on this page to explore all exceptions with their descriptions.
   *
   * Transaction handles uncaught exceptions thrown inside its scope, then aborts
@@ -247,13 +264,13 @@
   * Let's consider following example:
   * @snippet examples/mpsc_queue/mpsc_queue.cpp mpsc_main
   *
-  * There are plenty of try-catch blocks placed to handle possible errors that can happen in some conditions.
-  * E.g. @ref pmem::obj::pool<T>::open can lead to @ref pmem::pool_error.
-  * Next exception, **std::exception**, is placed to handle possible errors during allocation,
-  * coming from @ref pmem::obj::make_persistent. Worth being careful using every new function
-  * because some of exceptions are not obvious, e.g., pmem::obj::pool<T>::close
-  * at the end of the code which may throw **std::logic_error**.
+  * There are plenty of try-catch blocks placed to handle possible errors that can occur in some
+  * conditions. E.g. @ref pmem::obj::pool<T>::open can lead to @ref pmem::pool_error.
+  * The next exception, **std::exception**, is placed to handle possible errors during allocation,
+  * coming from @ref pmem::obj::make_persistent. Worth being careful using any new function
+  * because some exceptions are not obvious, e.g., pmem::obj::pool<T>::close
+  * at the end of the code, which may throw **std::logic_error**.
   *
-  * You should check every function you will use in context of possible
-  * exceptions and then handle them to avoid crash.
-  **/
+  * You should check every function you will use in the context of possible
+  * exceptions and then handle them to avoid a crash.
+  */