Update documentation

Author: endurodave

README.md

@@ -39,7 +39,7 @@ Synchronous and asynchronous delegates are available. Asynchronous variants hand
 Remote delegates enable function invocation across processes or processors by using customizable serialization and transport mechanisms. All argument data is marshaled to support remote callable endpoints with any function signature. Minimal effort is required to extend support to any new library. Concrete examples are provided using support libraries below. 
 
 * **Serialization:** [MessagePack](https://msgpack.org/index.html), [RapidJSON](https://github.com/Tencent/rapidjson), [MessageSerialize](https://github.com/endurodave/MessageSerialize)
-* **Transport:** [ZeroMQ](https://zeromq.org/), UDP, Data Pipe, memory buffer
+* **Transport:** [ZeroMQ](https://zeromq.org/), UDP, data pipe, memory buffer
  
 It is always safe to call the delegate. In its null state, a call will not perform any action and will return a default-constructed return value. A delegate behaves like a normal pointer type: it can be copied, compared for equality, called, and compared to `nullptr`. Const correctness is maintained; stored const objects can only be called by const member functions.
 
@@ -63,6 +63,12 @@ Typical use cases are:
 
 The DelegateMQ library asynchronous features differ from `std::async` in that the caller-specified thread of control is used to invoke the target function bound to the delegate, rather than a random thread from the thread pool. The asynchronous variants copy the argument data into an event queue, ensuring safe transport to the destination thread, regardless of the argument type. This approach provides 'fire and forget' functionality, allowing the caller to avoid waiting or worrying about out-of-scope stack variables being accessed by the target thread.
 
+DelegateMQ uses an external thread, transport, and serializer, all of which are based on simple, well-defined interfaces.
+
+<img src="docs/LayerDiagram.jpg" alt="DelegateMQ Layer Diagram" style="width:60%;"><br>
+*DelegateMQ Layer Diagram*
+
+
 Originally published on CodeProject at: <a href="https://www.codeproject.com/Articles/5277036/Asynchronous-Multicast-Delegates-in-Modern-Cpluspl">Asynchronous Multicast Delegates in Modern C++</a>
 
 # Documentation
@@ -81,11 +87,32 @@ Originally published on CodeProject at: <a href="https://www.codeproject.com/Art
 
 See [Example Projects](docs/DETAILS.md#example-projects) to build other project examples.
 
+# Features
+
+DelegateMQ features at a glance. 
+
+| Feature | DelegateMQ |
+| --- | --- |
+| Purpose | DelegateMQ is a library used for invoking any callable synchronously, asynchronously, or remotely |
+| Usages | Callbacks (synchronous and asynchronous), asynchronous API's, communication and data distribution, and more |
+| Library | Allows customizing data sharing between threads, processes, or processors |
+| Complexity | Lightweight and extensible through external library interfaces and full source code |
+| Threading | No internal threads. External configurable thread interface portable to any OS (`IThread`). |
+| Serialization | External configurable serialization data formats, such as MessagePack, RapidJSON, or custom encoding (`ISerializer`) |
+| Transport | External configurable transport, such as ZeroMQ, TCP, UDP, serial, data pipe or any custom transport (`ITransport`)  |
+| Message Buffering | Provided by a communication library (e.g. ZeroMQ) or custom solution within transport |
+| Timeouts and Retries | Provided by a communication library (e.g. ZeroMQ REQ-REP (Request-Reply)), TCP/IP stack, or custom solution |
+| Dynamic Memory | Heap or DelegateMQ fixed-block allocator |
+| Error Handling | Configurable for return error code, assert or exception |
+| Embedded Friendly | Yes. Any OS such as Windows, Linux and FreeRTOS. An OS is not required (i.e. "superloop"). |
+| Operation System | Any. Custom `IThread` implementation may be required. |
+| Language | C++17 or higher |
+
 # Related Repositories
 
 ## Alternative Implementations
 
-Alternative asynchronous implementations similar in concept to C++ delegates, simpler, and less features.
+Alternative asynchronous implementations similar in concept to DelegateMQ, simpler, and less features.
 
 * <a href="https://github.com/endurodave/AsyncCallback">Asynchronous Callbacks in C++</a> - A C++ asynchronous callback framework.
 * <a href="https://github.com/endurodave/C_AsyncCallback">Asynchronous Callbacks in C</a> - A C language asynchronous callback framework.

docs/DETAILS.md

@@ -2,6 +2,7 @@
 [![conan Ubuntu](https://github.com/endurodave/cpp-async-delegate/actions/workflows/cmake_ubuntu.yml/badge.svg)](https://github.com/endurodave/cpp-async-delegate/actions/workflows/cmake_ubuntu.yml)
 [![conan Ubuntu](https://github.com/endurodave/cpp-async-delegate/actions/workflows/cmake_clang.yml/badge.svg)](https://github.com/endurodave/cpp-async-delegate/actions/workflows/cmake_clang.yml)
 [![conan Windows](https://github.com/endurodave/cpp-async-delegate/actions/workflows/cmake_windows.yml/badge.svg)](https://github.com/endurodave/cpp-async-delegate/actions/workflows/cmake_windows.yml)
+[![Codecov](https://codecov.io/gh/endurodave/cpp-async-delegate/branch/master/graph/badge.svg)](https://app.codecov.io/gh/endurodave/cpp-async-delegate)
 
 # Delegates in C++
 
@@ -16,6 +17,7 @@ The DelegateMQ C++ library can invoke any callable function synchronously, async
   - [Build Options](#build-options)
   - [Example Projects](#example-projects)
   - [Examples Setup](#examples-setup)
+  - [Build Integration](#build-integration)
 - [Quick Start](#quick-start)
   - [Basic Examples](#basic-examples)
   - [Publish/Subscribe Example](#publishsubscribe-example)
@@ -110,16 +112,11 @@ The DelegateMQ C++ library can invoke any callable function synchronously, async
 
 [CMake](https://cmake.org/) is used to create the project files in the `build` directory. The repository root project executes all unit tests and examples with no external code or library dependencies.
 
-`cmake -B build`
+`cmake -B build .`
 
 ## Build Options
 
-The build options are contained within the files below.
-
-| File Name | Settings |
-| --- | --- |
-| `DelegateOpt.h` | `USE_ASSERTS` enable macro to use asserts instead of exceptions.<br>`USE_ALLOCATOR` enable macro to use a fixed-block allocator instead of the global heap. |
-| `External.cmake` | Update directory locations for external libraries such as MessagePack, RapidJSON, ZeroMQ, and FreeRTOS. |
+The DelegateMQ build options are located within `DelegateMQ.cmake`. Customize the external library paths using `External.cmake`. 
 
 ## Example Projects
 
@@ -139,10 +136,53 @@ Some remote delegate example projects have external library dependencies. Follow
 6. Clone [FreeRTOS](https://github.com/FreeRTOS/FreeRTOS).
 7. Edit DelegateMQ `External.cmake` file and update external library directory locations.
 9. Build any example subproject within the `example/sample-projects` directory.<br>
-   `cmake -B build`
+   `cmake -B build .`
 
 See [Sample Projects](#sample-projects) for details regarding each sample project.
 
+## Build Integration
+
+Follow these steps to integrate DelegateMQ into a project.
+
+Set the desired DMQ options and include `DelegateMQ.cmake` within your `CMakeLists.txt` file.
+
+```
+# Set build options
+set (DMQ_EXTERNAL_LIB "ON")
+set (DMQ_ALLOCATOR "OFF")
+set (DMQ_UTIL "ON")
+set (DMQ_THREAD "DMQ_THREAD_STDLIB")
+set (DMQ_SERIALIZE "DMQ_SERIALIZE_MSGPACK")
+set (DMQ_TRANSPORT "DMQ_TRANSPORT_ZEROMQ")
+include("${CMAKE_SOURCE_DIR}/../../../../src/delegate-mq/DelegateMQ.cmake")
+```
+
+Update `External.cmake` external library paths.
+
+Add `DMQ_PREDEF_SOURCES` to your sources If using the predefined supporting DelegateMQ classes (e.g. `Thread`, `Serialize`, ...).
+
+```
+# Collect DelegateMQ predef source files
+list(APPEND SOURCES ${DMQ_PREDEF_SOURCES})
+```
+
+Add the DelegateMQ include directory path.
+
+```
+include_directories(${DMQ_ROOT_DIR})
+```
+
+Add external library include paths defined within `External.cmake` as necessary.
+
+```
+include_directories(    
+    ${VCPKG_ROOT_DIR}/include
+    ${MSGPACK_INCLUDE_DIR}
+)
+```
+
+Include `DelegateMQ.h` to use the delegate library. Build and execute the project.
+
 # Quick Start
 
 ## Basic Examples
@@ -901,7 +941,7 @@ In short, the DelegateMQ library offers features that are not natively available
 
 # Library
 
-A single include `DelegateMQ.h` provides access to all delegate library features. The library is wrapped within a `DelegateMQ` namespace. The table below shows the delegate class hierarchy.
+A single include `DelegateMQ.h` provides access to all delegate library features. The library is wrapped within a `dmq` namespace. The table below shows the delegate class hierarchy.
 
 ```cpp
 // Delegates
@@ -1091,7 +1131,7 @@ if (thread) {
 `DispatchDelegate()` inserts a message into the thread message queue. `Thread` class uses a underlying `std::thread`. `Thread` is an implementation detail; create a unique `DispatchDelegate()` function based on the platform operating system API.
 
 ```cpp
-void Thread::DispatchDelegate(std::shared_ptr<DelegateMQ::DelegateMsg> msg)
+void Thread::DispatchDelegate(std::shared_ptr<dmq::DelegateMsg> msg)
 {
     if (m_thread == nullptr)
         throw std::invalid_argument("Thread pointer is null");
@@ -1560,14 +1600,15 @@ See the `examples/sample-code` directory for additional examples.
 
 ## Sample Projects
 
-See the `examples/sample-projects` directory for example project. Most projects run on Windows or Linux. Others are Windows-only.
+See the `examples/sample-projects` directory for example project. Most projects run on Windows or Linux. Others are Windows-only. See [Examples Setup](#examples-setup) before running sample projects.
 
 ### bare-metal
 
 Remote delegate example with no external libraries. 
 
 | Interface | Implementation |
 | --- | --- |
+| `IThread` | `Thread` class implemented using `std::thread`. 
 | `ISerializer` | Insertion `operator<<` and extraction `operator>>` operators. 
 | `IDispatcher` | Shared sender/receiver `std::stringstream` for dispatcher transport.
 
@@ -1577,6 +1618,7 @@ Remote delegate example using FreeRTOS and no external libraries. Tested using t
 
 | Interface | Implementation |
 | --- | --- |
+| `IThread` | `Thread` class implemented using FreeRTOS. 
 | `ISerializer` | Insertion `operator<<` and extraction `operator>>` operators. 
 | `IDispatcher` | Shared sender/receiver `std::stringstream` for dispatcher transport.
 
@@ -1586,6 +1628,7 @@ Remote delegate example with Windows pipe and `serialize`.
 
 | Interface | Implementation |
 | --- | --- |
+| `IThread` | `Thread` class implemented using `std::thread`. 
 | `ISerializer` | `serialize` class.
 | `IDispatcher` | Windows data pipe for dispatcher transport.
 
@@ -1595,6 +1638,7 @@ Remote delegate example with Windows UDP socket and `serialize`.
 
 | Interface | Implementation |
 | --- | --- |
+| `IThread` | `Thread` class implemented using `std::thread`. 
 | `ISerializer` | `serialize` class.
 | `IDispatcher` | Windows UDP socket for dispatcher transport.
 
@@ -1604,6 +1648,7 @@ Remote delegate example using ZeroMQ and `serialize`.
 
 | Interface | Implementation |
 | --- | --- |
+| `IThread` | `Thread` class implemented using `std::thread`. 
 | `ISerializer` | `serialize` class.  
 | `IDispatcher` | ZeroMQ library for dispatcher transport.
 
@@ -1613,6 +1658,7 @@ Remote delegate example using ZeroMQ and MessagePack libraries.
 
 | Interface | Implementation |
 | --- | --- |
+| `IThread` | `Thread` class implemented using `std::thread`. 
 | `ISerializer` | MessagePack library.  
 | `IDispatcher` | ZeroMQ library for dispatcher transport.
 
@@ -1622,6 +1668,7 @@ Remote delegate example using ZeroMQ and RapidJSON libraries.
 
 | Interface | Implementation |
 | --- | --- |
+| `IThread` | `Thread` class implemented using `std::thread`. 
 | `ISerializer` | RapidJSON library.  
 | `IDispatcher` | ZeroMQ library for dispatcher transport.
 
@@ -1631,6 +1678,7 @@ Remote delegate example showing a complex system architecture using ZeroMQ and M
 
 | Interface | Implementation |
 | --- | --- |
+| `IThread` | `Thread` class implemented using `std::thread`. 
 | `ISerializer` | MessagePack library. | 
 | `IDispatcher` | ZeroMQ library for dispatcher transport. |
 

docs/LayerDiagram.jpg

@@ -114,7 +114,7 @@
 <div class="line"><a id="l00028" name="l00028"></a><span class="lineno">   28</span>    <span class="comment">// Is the calling function executing on the requested thread?</span></div>
 <div class="line"><a id="l00029" name="l00029"></a><span class="lineno">   29</span>    <span class="keywordflow">if</span> (thread.<a class="code hl_function" href="class_thread.html#a2294b75a90c36b4f14e32ae8d975a0fb">GetThreadId</a>() != <a class="code hl_function" href="class_thread.html#aafe48fc7ef98b9e6adcf7b188a30e35a">Thread::GetCurrentThreadId</a>()) {</div>
 <div class="line"><a id="l00030" name="l00030"></a><span class="lineno">   30</span>        <span class="comment">// Create a delegate that points to func to invoke on thread</span></div>
-<div class="line"><a id="l00031" name="l00031"></a><span class="lineno">   31</span>        <span class="keyword">auto</span> delegate = <a class="code hl_function" href="namespace_delegate_m_q.html#a1087b41a3217d76f1744f5c83dbe9d72">DelegateMQ::MakeDelegate</a>(func, thread, timeout);</div>
+<div class="line"><a id="l00031" name="l00031"></a><span class="lineno">   31</span>        <span class="keyword">auto</span> delegate = <a class="code hl_function" href="namespacedmq.html#a65e308cc5f3e37d2f7f89c72b9744ae2">dmq::MakeDelegate</a>(func, thread, timeout);</div>
 <div class="line"><a id="l00032" name="l00032"></a><span class="lineno">   32</span> </div>
 <div class="line"><a id="l00033" name="l00033"></a><span class="lineno">   33</span>        <span class="comment">// Invoke the delegate target function asynchronously and wait for function call to complete</span></div>
 <div class="line"><a id="l00034" name="l00034"></a><span class="lineno">   34</span>        <span class="keyword">auto</span> retVal = delegate.AsyncInvoke(std::forward&lt;Args&gt;(args)...);</div>
@@ -147,7 +147,7 @@
 <div class="line"><a id="l00068" name="l00068"></a><span class="lineno">   68</span>    <span class="comment">// Is the calling function executing on the requested thread?</span></div>
 <div class="line"><a id="l00069" name="l00069"></a><span class="lineno">   69</span>    <span class="keywordflow">if</span> (thread.<a class="code hl_function" href="class_thread.html#a2294b75a90c36b4f14e32ae8d975a0fb">GetThreadId</a>() != <a class="code hl_function" href="class_thread.html#aafe48fc7ef98b9e6adcf7b188a30e35a">Thread::GetCurrentThreadId</a>()) {</div>
 <div class="line"><a id="l00070" name="l00070"></a><span class="lineno">   70</span>        <span class="comment">// Create a delegate that points to func to invoke on thread</span></div>
-<div class="line"><a id="l00071" name="l00071"></a><span class="lineno">   71</span>        <span class="keyword">auto</span> delegate = <a class="code hl_function" href="namespace_delegate_m_q.html#a1087b41a3217d76f1744f5c83dbe9d72">DelegateMQ::MakeDelegate</a>(tclass, func, thread, timeout);</div>
+<div class="line"><a id="l00071" name="l00071"></a><span class="lineno">   71</span>        <span class="keyword">auto</span> delegate = <a class="code hl_function" href="namespacedmq.html#a65e308cc5f3e37d2f7f89c72b9744ae2">dmq::MakeDelegate</a>(tclass, func, thread, timeout);</div>
 <div class="line"><a id="l00072" name="l00072"></a><span class="lineno">   72</span> </div>
 <div class="line"><a id="l00073" name="l00073"></a><span class="lineno">   73</span>        <span class="comment">// Invoke the delegate target function asynchronously and wait for function call to complete</span></div>
 <div class="line"><a id="l00074" name="l00074"></a><span class="lineno">   74</span>        <span class="keyword">auto</span> retVal = delegate.AsyncInvoke(std::forward&lt;Args&gt;(args)...);</div>
@@ -178,7 +178,7 @@
 <div class="ttc" id="aclass_thread_html"><div class="ttname"><a href="class_thread.html">Thread</a></div><div class="ttdef"><b>Definition</b> freertos/Thread.h:19</div></div>
 <div class="ttc" id="aclass_thread_html_a2294b75a90c36b4f14e32ae8d975a0fb"><div class="ttname"><a href="class_thread.html#a2294b75a90c36b4f14e32ae8d975a0fb">Thread::GetThreadId</a></div><div class="ttdeci">TaskHandle_t GetThreadId()</div><div class="ttdoc">Get the ID of this thread instance.</div><div class="ttdef"><b>Definition</b> freertos/Thread.cpp:51</div></div>
 <div class="ttc" id="aclass_thread_html_aafe48fc7ef98b9e6adcf7b188a30e35a"><div class="ttname"><a href="class_thread.html#aafe48fc7ef98b9e6adcf7b188a30e35a">Thread::GetCurrentThreadId</a></div><div class="ttdeci">static TaskHandle_t GetCurrentThreadId()</div><div class="ttdoc">Get the ID of the currently executing thread.</div><div class="ttdef"><b>Definition</b> freertos/Thread.cpp:62</div></div>
-<div class="ttc" id="anamespace_delegate_m_q_html_a1087b41a3217d76f1744f5c83dbe9d72"><div class="ttname"><a href="namespace_delegate_m_q.html#a1087b41a3217d76f1744f5c83dbe9d72">DelegateMQ::MakeDelegate</a></div><div class="ttdeci">auto MakeDelegate(RetType(*func)(Args... args))</div><div class="ttdoc">Creates a delegate that binds to a free function.</div><div class="ttdef"><b>Definition</b> Delegate.h:670</div></div>
+<div class="ttc" id="anamespacedmq_html_a65e308cc5f3e37d2f7f89c72b9744ae2"><div class="ttname"><a href="namespacedmq.html#a65e308cc5f3e37d2f7f89c72b9744ae2">dmq::MakeDelegate</a></div><div class="ttdeci">auto MakeDelegate(RetType(*func)(Args... args))</div><div class="ttdoc">Creates a delegate that binds to a free function.</div><div class="ttdef"><b>Definition</b> Delegate.h:670</div></div>
 </div><!-- fragment --></div><!-- contents -->
 </div><!-- doc-content -->
 <!-- start footer part -->