Introduce policies and allow observer_from_this in constructors

README.md

@@ -13,6 +13,8 @@ Built and tested on:
 
 - [Introduction](#introduction)
 - [Usage](#usage)
+- [enable_observer_from_this](#enable_observer_from_this)
+- [Policies](#policies)
 - [Limitations](#limitations)
 - [Comparison spreadsheet](#comparison-spreadsheet)
 - [Speed benchmarks](#speed-benchmarks)
@@ -83,7 +85,19 @@ int main() {
 }
 ```
 
-As with `std::shared_ptr`/`std::weak_ptr`, if you need to obtain an observer pointer to an object when you only have `this` (i.e., from a member function), you can inherit from `oup::enable_observer_from_this<T>` to gain access to the `observer_from_this()` member function. This function will return a valid observer pointer as long as the object is owned by a unique or sealed pointer, and will return `nullptr` in all other cases. Contrary to `std::enable_shared_from_this<T>`, this feature naturally supports multiple inheritance.
+
+## enable_observer_from_this
+
+As with `std::shared_ptr`/`std::weak_ptr`, if you need to obtain an observer pointer to an object when you only have `this` (i.e., from a member function), you can inherit from `oup::enable_observer_from_this_unique<T>` or `oup::enable_observer_from_this_sealed<T>` (depending on the type of the owner pointer) to gain access to the `observer_from_this()` member function. Contrary to `std::enable_shared_from_this<T>`, this function is `noexcept` and is able to return a valid observer pointer at all times, even if the object is being constructed or is not owned by a unique or sealed pointer. Also contrary to `std::enable_shared_from_this<T>`, this feature naturally supports multiple inheritance.
+
+To achieve this, the price to pay is that `oup::enable_observer_from_this_unique<T>` uses virtual inheritance, while `oup::enable_observer_from_this_sealed<T>` requires `T`'s constructor to take a control block as input (thereby preventing `T` from being default-constructible, copiable, or movable). If needed, these trade-offs can be controlled by policies, see below.
+
+
+## Policies
+
+Similarly to `std::string` and `std::basic_string`, this library provides both "convenience" types (`oup::observable_unique_ptr<T,Deleter>`, `oup::observable_sealed_ptr<T>`, `oup::observer_ptr<T>`, `oup::enable_observable_from_this_unique<T>`, `oup::enable_observable_from_this_sealed<T>`) and "generic" types (`oup::basic_observable_ptr<T,Deleter,Policy>`, `oup::basic_observer_ptr<T,ObsPolicy>`, `oup::basic_enable_observable_from_this<T,Policy>`).
+
+If the trade-offs chosen to defined the "convenience" types are not appropriate for your use cases, they can be fine-tuned using the generic classes and providing your own choice of policies. Please refer to the documentation for more information on policies. In particular, policies will control most of the API and behavior of the `enable_observable_from_this` feature, as well as allowing you to tune the size of the reference counting object (speed/memory trade-off).
 
 
 ## Limitations
@@ -117,23 +131,25 @@ Labels:
 | Support arrays           | yes  | yes    | no       | yes    | yes    | no         | no         |
 | Support custom allocator | N/A  | yes    | no       | yes    | yes    | no         | no         |
 | Support custom deleter   | N/A  | N/A    | N/A      | yes    | yes(4) | yes        | no         |
-| Number of heap alloc.    | 0    | 0      | 0        | 1      | 1/2(5) | 2          | 1          |
+| Max number of observers  | inf. | ?(5)   | 2^31 - 1 | 1      | ?(5)   | 1          | 1          |
+| Number of heap alloc.    | 0    | 0      | 0        | 1      | 1/2(6) | 2          | 1          |
 | Size in bytes (64 bit)   |      |        |          |        |        |            |            |
 |  - Stack (per instance)  | 8    | 16     | 16       | 8      | 16     | 16         | 16         |
-|  - Heap (shared)         | 0    | 0      | 0        | 0      | 24     | 8          | 8          |
-|  - Total                 | 8    | 16     | 16       | 8      | 40     | 24         | 24         |
+|  - Heap (shared)         | 0    | 0      | 0        | 0      | 24     | 4          | 4          |
+|  - Total                 | 8    | 16     | 16       | 8      | 40     | 20         | 20         |
 | Size in bytes (32 bit)   |      |        |          |        |        |            |            |
 |  - Stack (per instance)  | 4    | 8      | 8        | 4      | 8      | 8          | 8          |
-|  - Heap (shared)         | 0    | 0      | 0        | 0      | 16     | 8          | 8          |
-|  - Total                 | 4    | 8      | 8        | 4      | 24     | 16         | 16         |
+|  - Heap (shared)         | 0    | 0      | 0        | 0      | 16     | 4          | 4          |
+|  - Total                 | 4    | 8      | 8        | 4      | 24     | 12         | 12         |
 
 Notes:
 
  - (1) If `expired()` returns true, the pointer is guaranteed to remain `nullptr` forever, with no race condition. If `expired()` returns false, the pointer could still expire on the next instant, which can lead to race conditions.
  - (2) By construction, only one thread can own the pointer, therefore deletion is thread-safe.
  - (3) Yes if using `std::atomic<std::shared_ptr<T>>` and `std::atomic<std::weak_ptr<T>>`.
  - (4) Not if using `std::make_shared()`.
- - (5) 2 by default, or 1 if using `std::make_shared()`.
+ - (5) Not defined by the C++ standard. In practice, libstdc++ stores its reference count on an `_Atomic_word`, which for a common 64bit linux platform is a 4 byte signed integer, hence the limit will be 2^31 - 1. Microsoft's STL uses `_Atomic_counter_t`, which for a 64bit Windows platform is 4 bytes unsigned integer, hence the limit will be 2^32 - 1.
+ - (6) 2 by default, or 1 if using `std::make_shared()`.
 
 
 ## Speed benchmarks
@@ -152,6 +168,8 @@ Detail of the benchmarks:
  - Create observer copy: construct a new observer pointer from another observer pointer.
  - Dereference observer: get a reference to the underlying object from an observer pointer.
 
+The benchmarks were last ran for v0.4.0.
+
 *Compiler: gcc 9.3.0, std: libstdc++, OS: linux 5.1.0, CPU: Ryzen 5 2600:*
 
 | Pointer                  | raw/unique | weak/shared | observer/obs_unique | observer/obs_sealed |

doc/dox.conf

@@ -514,22 +514,22 @@ EXTRACT_ANON_NSPACES   = NO
 # section is generated. This option has no effect if EXTRACT_ALL is enabled.
 # The default value is: NO.
 
-HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_MEMBERS     = YES
 
 # If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all
 # undocumented classes that are normally visible in the class hierarchy. If set
 # to NO, these classes will be included in the various overviews. This option
 # has no effect if EXTRACT_ALL is enabled.
 # The default value is: NO.
 
-HIDE_UNDOC_CLASSES     = NO
+HIDE_UNDOC_CLASSES     = YES
 
 # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend
 # declarations. If set to NO, these declarations will be included in the
 # documentation.
 # The default value is: NO.
 
-HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_FRIEND_COMPOUNDS  = YES
 
 # If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any
 # documentation blocks found inside the body of a function. If set to NO, these
@@ -889,7 +889,7 @@ EXCLUDE_PATTERNS       =
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories use the pattern */test/*
 
-EXCLUDE_SYMBOLS        =
+EXCLUDE_SYMBOLS        = T, Deleter, enable_observer_from_this_base, inherit_as_virtual, ptr_and_deleter, details
 
 # The EXAMPLE_PATH tag can be used to specify one or more files or directories
 # that contain example code fragments that are included (see the \include