iox-eclipse-iceoryx#1640 Update documentation

Signed-off-by: Matthias Killat <[email protected]>

doc/design/polymorphic_handler.md

@@ -14,17 +14,17 @@ that also inherits from `I`
 1. Any attempt to change the handler after it is finalized, shall call an function that has access
    to the current and new handler (for e.g. logging).
 
-The handler itself may not be thread-safe and multiple threads can concurrently use it. If this is
-desired, the classes implementing `I` must be thread-safe.
-
 To achieve this, we define another support class `StaticLifeTimeGuard` that solves the singleton lifetime problem.
 This class can be used on its own and is based on the nifty counter reference counting.
 
+The handler itself may not be thread-safe and multiple threads can concurrently use it. 
+If thread-safety of the instances is desired, the classes implementing `I` must be thread-safe.
+
 ## StaticLifetimeGuard
 
 ### Properties
 
-1. Manage a singleon instance of some type `T`
+1. Manage a singleton instance of some type `T`
 1. Lazy initialization on first use
 1. Thread-safe instance construction
 1. Provide a thread-safe way of obtaining the instance
@@ -51,6 +51,10 @@ static Foo& fooInstance = StaticLifetimeGuard<Foo>::instance();
 // the fooInstance is guaranteed destroyed after guard is destroyed
 // guard could also be held by another static
 
+// alternatively call a static function on the guard (well-defined)
+static Foo& sameFooInstance = guard.instance();
+
+// &fooInstance and &sameFooInstance are equal
 ```
 
 ### Manage static singleton lifetime dependencies
@@ -113,15 +117,15 @@ Due to atomic counter decrement, the instance is destroyed exactly once.
 
 ### Instance construction after destruction
 
-It is not possible replace the instance once constructed due to the static primary guard.
+It is not possible to replace the instance once constructed due to the static primary guard.
 Technically it would be possible by some static destructor after the primary guard (and all other
 guards) are destroyed, but this happens only during program termination.
 
 ## Using the Polymorphic Handler
 
 ### The Activatable interface
 
-To allow atomic acivation and deactivation of the handler without the use of mutexes, we require the
+To allow atomic activation and deactivation of the handler without the use of mutexes, we require the
 interface `I` to implement the `Activatable` interface (basically a concept). This just uses an atomic
 flag and provides two functions to set and unset the flag.
 
@@ -244,16 +248,3 @@ main exits (or longer, with explicit guards), the individual handlers are not ne
 thread-safe. This has to be ensured by the implementation of the `Interface`. In particular
 `DefaultHandler` and any other handler derived from `Interface` must be thread-safe if it is to be
 used by multiple threads.
-
-
-
-
-
-
-
-
-
-
-
-
-

iceoryx_hoofs/include/iceoryx_hoofs/design_pattern/static_lifetime_guard.hpp

@@ -19,6 +19,7 @@
 
 #include <atomic>
 #include <type_traits>
+#include <utility>
 
 namespace iox
 {
@@ -32,7 +33,9 @@ namespace design_pattern
 /// of the instance at least until G is destroyed
 /// @tparam T the type of the instance to be guarded
 ///
-/// @note dtor, ctor and copy ctor and instance are thread-safe
+/// @note all public functions except setCount are thread-safe
+/// @attention setCount is only supposed to be used while no guards are created
+/// concurrently
 ///
 /// @code
 /// // instance will be destroyed after guard
@@ -53,7 +56,7 @@ class StaticLifetimeGuard
 
     ~StaticLifetimeGuard() noexcept;
 
-    // assignment has no real purpose since the objects have no state,
+    // assignment does nothing since the objects have no state,
     // copy and move exist to support passing/returning a value object
     StaticLifetimeGuard& operator=(const StaticLifetimeGuard&) noexcept = default;
     StaticLifetimeGuard& operator=(StaticLifetimeGuard&&) noexcept = default;
@@ -73,6 +76,11 @@ class StaticLifetimeGuard
     /// @note This can be used to additionally extend or shorten the instance lifetime,
     /// This has to be done carefully, to ensure destruction or prevent early destruction.
     /// It is useful for testing purposes.
+    /// @attention setCount is only supposed to be used while no guards are created
+    /// concurrently as it will influence the guard mechanism.
+    /// The instance is destroyed once the counter reaches zero upon destruction of a guard,
+    /// i.e. changing the counter may lead to the instance never being destroyed
+    /// or being destroyed before the last guard.
     static uint64_t setCount(uint64_t count);
 
     /// @brief Get the current count value.

iceoryx_hoofs/include/iceoryx_hoofs/internal/design_pattern/polymorphic_handler.inl

@@ -174,4 +174,4 @@ PolymorphicHandler<Interface, Default, Hooks>::guard() noexcept
 } // namespace design_pattern
 } // namespace iox
 
-#endif // IOX_HOOFS_DESIGN_PATTERN_POLYMORPHIC_HANDLER_INL
+#endif // IOX_HOOFS_DESIGN_PATTERN_POLYMORPHIC_HANDLER_INL