Update example code, delegate containers, and serializers.

Author: endurodave

docs/DETAILS.md

@@ -65,6 +65,7 @@ The DelegateMQ C++ library enables function invocations on any callable, either
     - [Blocking Reinvoke](#blocking-reinvoke)
   - [Timer Example](#timer-example)
   - [`std::async` Thread Targeting Example](#stdasync-thread-targeting-example)
+  - [Remote Delegate Example](#remote-delegate-example)
   - [More Examples](#more-examples)
   - [Sample Projects](#sample-projects)
     - [system-architecture](#system-architecture)
@@ -432,6 +433,7 @@ A delegate container stores one or more delegates. A delegate container is calla
 ```cpp
 // Delegate Containers
 UnicastDelegate<>
+    UnicastDelegateSafe<>
 MulticastDelegate<>
     MulticastDelegateSafe<>
 ``` 
@@ -966,6 +968,7 @@ DelegateBase
 
 // Delegate Containers
 UnicastDelegate<>
+    UnicastDelegateSafe<>
 MulticastDelegate<>
     MulticastDelegateSafe<>
 ```
@@ -1097,6 +1100,8 @@ There is no way to asynchronously pass a C-style array by value. Avoid C-style a
 
 # Interfaces
 
+DelegateMQ interface classes allow customizing the library runtime behavior.
+
 ## `IThread`
 
 The `IThread` interface is used to send a delegate and argument data through a message queue. A delegate thread is required to dispatch asynchronous delegates to a specified target thread. The delegate library automatically constructs a `DelegateMsg` containing everything necessary for the destination thread.
@@ -1600,6 +1605,106 @@ void AsyncFutureExample()
     comm_thread.ExitThread();
 }
 ```
+## Remote Delegate Example
+
+Use a remote delegate to invoke a remote target function using [MessagePack](https://github.com/msgpack/msgpack-c/tree/cpp_master) (serialization) and [ZeroMQ](https://zeromq.org/) (transport). Code snippets below express the concept. See [system-architecture](#system-architecture) to execute this example.
+
+`NetworkMgr` class used by client and server applications handles communication with remote device. `SendAlarmMsg()` sends a message to the remote. `AlarmMsgCb` callback is used to receive the incoming message.
+
+```cpp
+#include "DelegateMQ.h"
+
+// NetworkMgr sends and receives data using a DelegateMQ transport implemented
+// with ZeroMQ and MessagePack libraries.
+class NetworkMgr
+{
+public:
+    static const dmq::DelegateRemoteId ALARM_MSG_ID = 1;
+
+    using AlarmFunc = void(AlarmMsg&, AlarmNote&);
+    using AlarmDel = dmq::MulticastDelegateSafe<AlarmFunc>;
+
+    // Receive callbacks for incoming messages by registering with this container
+    static AlarmDel AlarmMsgCb;
+
+    int Create();
+
+    // Send alarm message to the remote
+    void SendAlarmMsg(AlarmMsg& msg, AlarmNote& note);
+
+private:
+    // Serialize function argument data into a stream
+    xostringstream m_argStream;
+
+    // Transport using ZeroMQ library. Only call transport from NetworkMsg thread.
+    ZeroMqTransport m_transport;
+
+    // Dispatcher using DelegateMQ library
+    Dispatcher m_dispatcher;
+
+    // Alarm message remote delegate
+    Serializer<AlarmFunc> m_alarmMsgSer;
+    dmq::DelegateMemberRemote<AlarmDel, AlarmFunc> m_alarmMsgDel;
+};
+```
+
+At runtime, setup the remote delegate interface. A key point is the remote delegate (`m_alarmMsgDel`) binds directly to the `AlarmMsgCb` container (`dmq::MulticastDelegateSafe<AlarmFunc>`). Every incoming message generates one or more callbacks to registered listeners by binding `m_alarmMsgDel` remote delegate to the `AlarmMsgCb` container. A delegate may bind to any callable, and a delegate container is callable.
+
+```cpp
+int NetworkMgr::Create()
+{
+    // Reinvoke call onto NetworkMgr thread
+    if (Thread::GetCurrentThreadId() != m_thread.GetThreadId())
+        return MakeDelegate(this, &NetworkMgr::Create, m_thread, WAIT_INFINITE)();
+
+    // Setup the remote delegate interfaces
+    m_alarmMsgDel.SetStream(&m_argStream);
+    m_alarmMsgDel.SetSerializer(&m_alarmMsgSer);
+    m_alarmMsgDel.SetDispatcher(&m_dispatcher);
+    m_alarmMsgDel.SetErrorHandler(MakeDelegate(this, &NetworkMgr::ErrorHandler));
+
+    // Bind the remote delegate to the AlarmMsgCb delegate container
+    m_alarmMsgDel.Bind(&AlarmMsgCb, &AlarmDel::operator(), ALARM_MSG_ID);
+
+    // Set the transport used by the dispatcher
+    m_dispatcher.SetTransport(&m_transport);
+
+    return 1;
+}
+```
+
+Send message to the remote by calling the `m_alarmMsgDel` delegate on `m_thread` context. A ZeroMQ socket instance is not thread safe so ZeroMQ socket access is always on the `NetworkMgr` internal thread.
+
+```cpp
+void NetworkMgr::SendAlarmMsg(AlarmMsg& msg, AlarmNote& note)
+{
+    // Reinvoke call onto NetworkMgr thread
+    if (Thread::GetCurrentThreadId() != m_thread.GetThreadId())
+        return MakeDelegate(this, &NetworkMgr::SendAlarmMsg, m_thread)(msg, note);
+
+    // Send alarm to remote. Invoke remote delegate on m_thread only.
+    m_alarmMsgDel(msg, note);
+}
+```
+
+Client registers to receive remote delegate callbacks on the `AlarmMgr` private thread. 
+
+```cpp
+class AlarmMgr
+{
+    AlarmMgr()
+    {
+        // Register for alarm callback on m_thread
+        NetworkMgr::AlarmMsgCb += MakeDelegate(this, &AlarmMgr::RecvAlarmMsg, m_thread);
+    }
+
+    void RecvAlarmMsg(AlarmMsg& msg, AlarmNote& note)
+    {
+        // Handle incoming alarm message from remote
+    }
+};
+```
+
 ## More Examples
 
 See the `examples/sample-code` directory for additional examples.
@@ -1610,7 +1715,7 @@ See the `examples/sample-projects` directory for example project. Most projects
 
 ### system-architecture
 
-The System Architecture example demonstrates a complex client-server DelegateMQ application using the ZeroMQ and MessagePack support libraries. This example implements the acquisition of sensor and actuator data across two applications. It showcases communication and collaboration between subsystems, threads, and processes or processors. Delegate communication, callbacks, asynchronous APIs, and error handing are also highlighted. Notice how easily DelegateMQ transfers event data between threads and processes with minimal application code.
+The System Architecture example demonstrates a complex client-server DelegateMQ application using the ZeroMQ and MessagePack support libraries. This example implements the acquisition of sensor and actuator data across two applications. It showcases communication and collaboration between subsystems, threads, and processes or processors. Delegate communication, callbacks, asynchronous APIs, and error handing are also highlighted. Notice how easily DelegateMQ transfers event data between threads and processes with minimal application code. The application layer is completely isolated from message passing details.
 
 Execute the client and server projects to run the example.
 

example/sample-projects/system-architecture/client/ClientApp.h

@@ -31,7 +31,7 @@ class ClientApp
         // Callback to capture NetworkMgr::SendCommandMsg() success or error
         ErrorCallback errorCb = [&success, &cv](dmq::DelegateRemoteId id, dmq::DelegateError err, dmq::DelegateErrorAux aux) {
             // SendCommandMsg() ID?
-            if (id == COMMAND_MSG_ID) {
+            if (id == NetworkMgr::COMMAND_MSG_ID) {
                 // Send success?
                 if (err == dmq::DelegateError::SUCCESS)
                     success = true;

example/sample-projects/system-architecture/common/NetworkMgr.cpp

@@ -47,25 +47,26 @@ int NetworkMgr::Create()
     m_alarmMsgDel.SetSerializer(&m_alarmMsgSer);
     m_alarmMsgDel.SetDispatcher(&m_dispatcher);
     m_alarmMsgDel.SetErrorHandler(MakeDelegate(this, &NetworkMgr::ErrorHandler));
-    m_alarmMsgDel = MakeDelegate(this, &NetworkMgr::RecvAlarmMsg, ALARM_MSG_ID);
+    // Bind the remote delegate to the AlarmMsgCb delegate container for incoming msgs
+    m_alarmMsgDel.Bind(&AlarmMsgCb, &AlarmDel::operator(), ALARM_MSG_ID);
 
     m_dataMsgDel.SetStream(&m_argStream);
     m_dataMsgDel.SetSerializer(&m_dataMsgSer);
     m_dataMsgDel.SetDispatcher(&m_dispatcher);
     m_dataMsgDel.SetErrorHandler(MakeDelegate(this, &NetworkMgr::ErrorHandler));
-    m_dataMsgDel = MakeDelegate(this, &NetworkMgr::RecvDataMsg, DATA_MSG_ID);
+    m_dataMsgDel.Bind(&DataMsgCb, &DataDel::operator(), DATA_MSG_ID);
 
     m_commandMsgDel.SetStream(&m_argStream);
     m_commandMsgDel.SetSerializer(&m_commandMsgSer);
     m_commandMsgDel.SetDispatcher(&m_dispatcher);
     m_commandMsgDel.SetErrorHandler(MakeDelegate(this, &NetworkMgr::ErrorHandler));
-    m_commandMsgDel = MakeDelegate(this, &NetworkMgr::RecvCommandMsg, COMMAND_MSG_ID);
+    m_commandMsgDel.Bind(&CommandMsgCb, &CommandDel::operator(), COMMAND_MSG_ID);
 
     m_actuatorMsgDel.SetStream(&m_argStream);
     m_actuatorMsgDel.SetSerializer(&m_actuatorMsgSer);
     m_actuatorMsgDel.SetDispatcher(&m_dispatcher);
     m_actuatorMsgDel.SetErrorHandler(MakeDelegate(this, &NetworkMgr::ErrorHandler));
-    m_actuatorMsgDel = MakeDelegate(this, &NetworkMgr::RecvActuatorMsg, ACTUATOR_MSG_ID);
+    m_actuatorMsgDel.Bind(&ActuatorMsgCb, &ActuatorDel::operator(), ACTUATOR_MSG_ID);
 
     int err = 0;
 #ifdef SERVER_APP
@@ -81,7 +82,7 @@ int NetworkMgr::Create()
     // Set the transport used by the dispatcher
     m_dispatcher.SetTransport(&m_transport);
 
-    // Set receive async delegates into map
+    // Set remote delegate into map
     m_receiveIdMap[ALARM_MSG_ID] = &m_alarmMsgDel;
     m_receiveIdMap[COMMAND_MSG_ID] = &m_commandMsgDel;
     m_receiveIdMap[DATA_MSG_ID] = &m_dataMsgDel;
@@ -123,7 +124,7 @@ void NetworkMgr::SendAlarmMsg(AlarmMsg& msg, AlarmNote& note)
     if (Thread::GetCurrentThreadId() != m_thread.GetThreadId())
         return MakeDelegate(this, &NetworkMgr::SendAlarmMsg, m_thread)(msg, note);
 
-    // Send alarm to remote. 
+    // Send alarm to remote. Invoke remote delegate on m_thread only.
     m_alarmMsgDel(msg, note);
 }
 
@@ -145,18 +146,20 @@ void NetworkMgr::SendDataMsg(DataMsg& data)
     m_dataMsgDel(data);
 }
 
-// Async send an actuator command and block the caller waiting for the client 
-// to respond. The execution sequence numbers shown below.
+// Async send an actuator command and block the caller waiting until the client 
+// responds or timeout. The execution sequence numbers shown below.
 bool NetworkMgr::SendActuatorMsgWait(ActuatorMsg& msg)
 {
     // If caller is not executing on m_thread
     if (Thread::GetCurrentThreadId() != m_thread.GetThreadId())
     {
+        // *** Caller's thread executes this control brach ***
+
         bool success = false;
         std::mutex mtx;
         std::condition_variable cv;
 
-        // 1. Callback handler for transport monitor send status
+        // 5. Callback handler for transport monitor send status
         SendStatusCallback statusCb = [&success, &cv](uint16_t seqNum, dmq::DelegateRemoteId id, TransportMonitor::Status status) {
             if (id == ACTUATOR_MSG_ID) {
                 // Client received ActuatorMsg?
@@ -166,15 +169,15 @@ bool NetworkMgr::SendActuatorMsgWait(ActuatorMsg& msg)
             }
         };
 
-        // 2. Register for send status callback (success or failure)
+        // 1. Register for send status callback (success or failure)
         m_transportMonitor.SendStatusCb += dmq::MakeDelegate(statusCb);
 
-        // 3. Renvoke SendActuatorMsgWait() on m_thread context
+        // 2. Reinvoke SendActuatorMsgWait() on m_thread context
         MakeDelegate(this, &NetworkMgr::SendActuatorMsgWait, m_thread)(msg);
 
-        // 5. Wait for statusCb callback to be triggered on m_thread
+        // 3. Wait for statusCb callback to be triggered on m_thread
         std::unique_lock<std::mutex> lock(mtx);
-        if (cv.wait_for(lock, TIMEOUT + std::chrono::milliseconds(100)) == std::cv_status::timeout)
+        if (cv.wait_for(lock, TIMEOUT) == std::cv_status::timeout)
         {
             // A timeout should never happen. The transport monitor is setup for a max 
             // TIMEOUT, so success or failure should never cause cv_status::timeout
@@ -184,13 +187,17 @@ bool NetworkMgr::SendActuatorMsgWait(ActuatorMsg& msg)
         // 6. Unregister from status callback
         m_transportMonitor.SendStatusCb -= dmq::MakeDelegate(statusCb);
 
-        // 7. Return the blocking async function invoke status
+        // 7. Return the blocking async function invoke status to caller
         return success;
     }
+    else
+    {
+        // *** NetworkMgr::m_thread executes this control brach ***
 
-    // 4. Send actuator command to remote on m_thread. 
-    m_actuatorMsgDel(msg);
-    return true;
+        // 4. Send actuator command to remote on m_thread. 
+        m_actuatorMsgDel(msg);
+        return true;
+    }
 }
 
 // Poll called periodically on m_thread context
@@ -209,7 +216,8 @@ void NetworkMgr::Poll()
             auto receiveDelegate = m_receiveIdMap[header.GetId()];
             if (receiveDelegate)
             {
-                // Invoke the receiver target function with the sender's argument data
+                // Invoke the receiver target callable with the sender's 
+                // incoming argument data
                 receiveDelegate->Invoke(arg_data);
             }
             else
@@ -236,23 +244,4 @@ void NetworkMgr::SendStatusHandler(uint16_t seqNum, dmq::DelegateRemoteId id, Tr
     SendStatusCb(seqNum, id, status);
 }
 
-void NetworkMgr::RecvAlarmMsg(AlarmMsg& msg, AlarmNote& note)
-{
-    AlarmMsgCb(msg, note);
-}
-
-void NetworkMgr::RecvCommandMsg(CommandMsg& command)
-{
-    CommandMsgCb(command);
-}
-
-void NetworkMgr::RecvDataMsg(DataMsg& data)
-{
-    DataMsgCb(data);
-}
-
-void NetworkMgr::RecvActuatorMsg(ActuatorMsg& msg)
-{
-    ActuatorMsgCb(msg);
-}