Update delegate library

Author: endurodave

Delegate/Delegate.h

@@ -153,7 +153,7 @@ class DelegateFree<RetType(Args...)> : public Delegate<RetType(Args...)> {
         m_func = rhs.m_func; 
     }
 
-    /// @brief Invoke the bound delegate function synchronously. 
+    /// @brief Invoke the bound delegate function synchronously. Always safe to call.
     /// @param[in] args - the function arguments, if any.
     /// @return The bound function return value, if any. If empty delegate
     /// default return type returned. 
@@ -363,7 +363,7 @@ class DelegateMember<TClass, RetType(Args...)> : public Delegate<RetType(Args...
         m_func = rhs.m_func;
     }
 
-    /// @brief Invoke the bound delegate function synchronously. 
+    /// @brief Invoke the bound delegate function synchronously. Always safe to call.
     /// @param[in] args - the function arguments, if any.
     /// @return The bound function return value, if any. If empty delegate
     /// default return type returned. 
@@ -527,7 +527,12 @@ class DelegateFunction<RetType(Args...)> : public Delegate<RetType(Args...)> {
     /// @param[in] func The `std::function` to bind to the delegate. This function must 
     /// match the signature of the delegate.
     void Bind(FunctionType func) {
-        m_func = func;
+        try {
+            m_func = func;
+        }
+        catch (const std::bad_alloc&) {
+            BAD_ALLOC();
+        }
     }
 
     /// Compares two ClassType objects using the '<' operator.
@@ -555,7 +560,7 @@ class DelegateFunction<RetType(Args...)> : public Delegate<RetType(Args...)> {
         m_func = rhs.m_func;
     }
 
-    /// @brief Invoke the bound delegate function synchronously. 
+    /// @brief Invoke the bound delegate function synchronously. Always safe to call.
     /// @param[in] args - the function arguments, if any.
     /// @return The bound function return value, if any. If empty delegate
     /// default return type returned. 

Delegate/DelegateAsync.h

@@ -146,7 +146,7 @@ class DelegateFreeAsync<RetType(Args...)> : public DelegateFree<RetType(Args...)
     /// and copying the state of the current object to it. 
     /// @return A pointer to a new `ClassType` instance.
     /// @post The caller is responsible for deleting the clone object.
-    /// @throws std::bad_alloc If dynamic memory allocation fails and USE_ASSERTS no defined.
+    /// @throws std::bad_alloc If dynamic memory allocation fails and USE_ASSERTS not defined.
     virtual ClassType* Clone() const override {
         return new(std::nothrow) ClassType(*this);
     }
@@ -220,7 +220,7 @@ class DelegateFreeAsync<RetType(Args...)> : public DelegateFree<RetType(Args...)
     /// @details Invoke delegate function asynchronously and do not wait for return value.
     /// This function is called by the source thread. Dispatches the delegate data into the 
     /// destination thread message queue. `Invoke()` must be called by the destination 
-    /// thread to invoke the target function.
+    /// thread to invoke the target function. Always safe to call.
     /// 
     /// The `DelegateAsyncMsg` duplicates and copies the function arguments into heap memory. 
     /// The source thread is not required to place function arguments into the heap. The delegate
@@ -230,7 +230,7 @@ class DelegateFreeAsync<RetType(Args...)> : public DelegateFree<RetType(Args...)
     /// @return A default return value. The return value is *not* returned from the 
     /// target function. Do not use the return value.
     /// @post Do not use the return value as its not valid.
-    /// @throws std::bad_alloc If dynamic memory allocation fails and USE_ASSERTS no defined.
+    /// @throws std::bad_alloc If dynamic memory allocation fails and USE_ASSERTS not defined.
     virtual RetType operator()(Args... args) override {
         if (this->Empty())
             return RetType();
@@ -272,7 +272,7 @@ class DelegateFreeAsync<RetType(Args...)> : public DelegateFree<RetType(Args...)
     }
 
     /// @brief Invoke delegate function asynchronously. Do not wait for return value.
-    /// Called by the source thread.
+    /// Called by the source thread. Always safe to call.
     /// @param[in] args The function arguments, if any.
     void AsyncInvoke(Args... args) {
         operator()(std::forward<Args>(args)...);
@@ -446,7 +446,7 @@ class DelegateMemberAsync<TClass, RetType(Args...)> : public DelegateMember<TCla
     /// and copying the state of the current object to it. 
     /// @return A pointer to a new `ClassType` instance.
     /// @post The caller is responsible for deleting the clone object.
-    /// @throws std::bad_alloc If dynamic memory allocation fails and USE_ASSERTS no defined.
+    /// @throws std::bad_alloc If dynamic memory allocation fails and USE_ASSERTS not defined.
     virtual ClassType* Clone() const override {
         return new(std::nothrow) ClassType(*this);
     }
@@ -520,7 +520,7 @@ class DelegateMemberAsync<TClass, RetType(Args...)> : public DelegateMember<TCla
     /// @details Invoke delegate function asynchronously and do not wait for return value.
     /// This function is called by the source thread. Dispatches the delegate data into the 
     /// destination thread message queue. `Invoke()` must be called by the destination 
-    /// thread to invoke the target function.
+    /// thread to invoke the target function. Always safe to call.
     /// 
     /// The `DelegateAsyncMsg` duplicates and copies the function arguments into heap memory. 
     /// The source thread is not required to place function arguments into the heap. The delegate
@@ -530,7 +530,7 @@ class DelegateMemberAsync<TClass, RetType(Args...)> : public DelegateMember<TCla
     /// @return A default return value. The return value is *not* returned from the 
     /// target function. Do not use the return value.
     /// @post Do not use the return value as its not valid.
-    /// @throws std::bad_alloc If dynamic memory allocation fails and USE_ASSERTS no defined.
+    /// @throws std::bad_alloc If dynamic memory allocation fails and USE_ASSERTS not defined.
     virtual RetType operator()(Args... args) override {
         if (this->Empty())
             return RetType();
@@ -572,7 +572,7 @@ class DelegateMemberAsync<TClass, RetType(Args...)> : public DelegateMember<TCla
     }
 
     /// @brief Invoke delegate function asynchronously. Do not wait for return value.
-    /// Called by the source thread.
+    /// Called by the source thread. Always safe to call.
     /// @param[in] args The function arguments, if any.
     void AsyncInvoke(Args... args) {
         operator()(std::forward<Args>(args)...);
@@ -687,7 +687,7 @@ class DelegateFunctionAsync<RetType(Args...)> : public DelegateFunction<RetType(
     /// and copying the state of the current object to it. 
     /// @return A pointer to a new `ClassType` instance.
     /// @post The caller is responsible for deleting the clone object.
-    /// @throws std::bad_alloc If dynamic memory allocation fails and USE_ASSERTS no defined.
+    /// @throws std::bad_alloc If dynamic memory allocation fails and USE_ASSERTS not defined.
     virtual ClassType* Clone() const override {
         return new(std::nothrow) ClassType(*this);
     }
@@ -761,7 +761,7 @@ class DelegateFunctionAsync<RetType(Args...)> : public DelegateFunction<RetType(
     /// @details Invoke delegate function asynchronously and do not wait for return value.
     /// This function is called by the source thread. Dispatches the delegate data into the 
     /// destination thread message queue. `Invoke()` must be called by the destination 
-    /// thread to invoke the target function.
+    /// thread to invoke the target function. Always safe to call.
     /// 
     /// The `DelegateAsyncMsg` duplicates and copies the function arguments into heap memory. 
     /// The source thread is not required to place function arguments into the heap. The delegate
@@ -771,7 +771,7 @@ class DelegateFunctionAsync<RetType(Args...)> : public DelegateFunction<RetType(
     /// @return A default return value. The return value is *not* returned from the 
     /// target function. Do not use the return value.
     /// @post Do not use the return value as its not valid.
-    /// @throws std::bad_alloc If dynamic memory allocation fails and USE_ASSERTS no defined.
+    /// @throws std::bad_alloc If dynamic memory allocation fails and USE_ASSERTS not defined.
     virtual RetType operator()(Args... args) override {
         if (this->Empty())
             return RetType();
@@ -813,7 +813,7 @@ class DelegateFunctionAsync<RetType(Args...)> : public DelegateFunction<RetType(
     }
 
     /// @brief Invoke delegate function asynchronously. Do not wait for return value.
-    /// Called by the source thread.
+    /// Called by the source thread. Always safe to call.
     /// @param[in] args The function arguments, if any.
     void AsyncInvoke(Args... args) {
         operator()(std::forward<Args>(args)...);

Delegate/DelegateAsyncWait.h

@@ -193,7 +193,7 @@ class DelegateFreeAsyncWait<RetType(Args...)> : public DelegateFree<RetType(Args
     /// and copying the state of the current object to it. 
     /// @return A pointer to a new `ClassType` instance.
     /// @post The caller is responsible for deleting the clone object.
-    /// @throws std::bad_alloc If dynamic memory allocation fails and USE_ASSERTS no defined.
+    /// @throws std::bad_alloc If dynamic memory allocation fails and USE_ASSERTS not defined.
     virtual ClassType* Clone() const override {
         return new(std::nothrow) ClassType(*this);
     }
@@ -272,7 +272,7 @@ class DelegateFreeAsyncWait<RetType(Args...)> : public DelegateFree<RetType(Args
     /// @details Invoke delegate function asynchronously and wait for the return value.
     /// This function is called by the source thread. Dispatches the delegate data into the 
     /// destination thread message queue. `Invoke()` must be called by the destination 
-    /// thread to invoke the target function.
+    /// thread to invoke the target function. Always safe to call.
     /// 
     /// If the destination thread invokes the function within `m_timeout`, the return 
     /// value is obtained from the destination thread function call. If `m_timeout` expires 
@@ -340,7 +340,7 @@ class DelegateFreeAsyncWait<RetType(Args...)> : public DelegateFree<RetType(Args
     }
 
     /// @brief Invoke delegate function asynchronously and block for function return value.
-    /// Called by the source thread.
+    /// Called by the source thread. Always safe to call.
     /// @param[in] args The function arguments, if any.
     /// @return The bound function return value stored withing `std::optional`. Use  
     /// `has_value()` to check if the the return value is valid. `value()` contains 
@@ -596,7 +596,7 @@ class DelegateMemberAsyncWait<TClass, RetType(Args...)> : public DelegateMember<
     /// and copying the state of the current object to it. 
     /// @return A pointer to a new `ClassType` instance.
     /// @post The caller is responsible for deleting the clone object.
-    /// @throws std::bad_alloc If dynamic memory allocation fails and USE_ASSERTS no defined.
+    /// @throws std::bad_alloc If dynamic memory allocation fails and USE_ASSERTS not defined.
     virtual ClassType* Clone() const override {
         return new(std::nothrow) ClassType(*this);
     }
@@ -675,7 +675,7 @@ class DelegateMemberAsyncWait<TClass, RetType(Args...)> : public DelegateMember<
     /// @details Invoke delegate function asynchronously and wait for the return value.
     /// This function is called by the source thread. Dispatches the delegate data into the 
     /// destination thread message queue. `Invoke()` must be called by the destination 
-    /// thread to invoke the target function.
+    /// thread to invoke the target function. Always safe to call.
     /// 
     /// If the destination thread invokes the function within `m_timeout`, the return 
     /// value is obtained from the destination thread function call. If `m_timeout` expires 
@@ -743,7 +743,7 @@ class DelegateMemberAsyncWait<TClass, RetType(Args...)> : public DelegateMember<
     }
 
     /// @brief Invoke delegate function asynchronously and block for function return value.
-    /// Called by the source thread.
+    /// Called by the source thread. Always safe to call.
     /// @param[in] args The function arguments, if any.
     /// @return The bound function return value stored withing `std::optional`. Use  
     /// `has_value()` to check if the the return value is valid. `value()` contains 
@@ -918,7 +918,7 @@ class DelegateFunctionAsyncWait<RetType(Args...)> : public DelegateFunction<RetT
     /// and copying the state of the current object to it. 
     /// @return A pointer to a new `ClassType` instance.
     /// @post The caller is responsible for deleting the clone object.
-    /// @throws std::bad_alloc If dynamic memory allocation fails and USE_ASSERTS no defined.
+    /// @throws std::bad_alloc If dynamic memory allocation fails and USE_ASSERTS not defined.
     virtual ClassType* Clone() const override {
         return new(std::nothrow) ClassType(*this);
     }
@@ -997,7 +997,7 @@ class DelegateFunctionAsyncWait<RetType(Args...)> : public DelegateFunction<RetT
     /// @details Invoke delegate function asynchronously and wait for the return value.
     /// This function is called by the source thread. Dispatches the delegate data into the 
     /// destination thread message queue. `Invoke()` must be called by the destination 
-    /// thread to invoke the target function.
+    /// thread to invoke the target function. Always safe to call.
     /// 
     /// If the destination thread invokes the function within `m_timeout`, the return 
     /// value is obtained from the destination thread function call. If `m_timeout` expires 
@@ -1065,7 +1065,7 @@ class DelegateFunctionAsyncWait<RetType(Args...)> : public DelegateFunction<RetT
     }
 
     /// @brief Invoke delegate function asynchronously and block for function return value.
-    /// Called by the source thread.
+    /// Called by the source thread. Always safe to call.
     /// @param[in] args The function arguments, if any.
     /// @return The bound function return value stored withing `std::optional`. Use  
     /// `has_value()` to check if the the return value is valid. `value()` contains 

Delegate/DelegateLib.h

@@ -31,19 +31,24 @@
 /// 
 /// Typical use cases are:
 ///
-/// * Publish / Subscribe(Event - Driven Programming)
-/// * Thread - Safe Asynchronous API(Subsystem / Library)
-/// * Anonymous Thread - Safe Callbacks on Specified Thread
+/// * Asynchronous Method Invocation(AMI)
+/// * Publish / Subscribe(Observer) Pattern
+/// * Anonymous, Asynchronous Thread - Safe Callbacks
+/// * Event - Driven Programming
+/// * Thread - Safe Asynchronous API
+/// * Design Patterns(Active Object)
 ///
-/// The delegate library differs from `std::async` in that the caller-specified thread of 
-/// control is used to invoke the target function bound to the delegate. The asynchronous 
+/// The delegate library's 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 the event queue, ensuring safe transport to the 
-/// destination thread, regardless of the argument type. This approach offers 'fire and forget' 
-/// functionality without the caller waiting.
+/// 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.
 /// 
-/// The `Async` and `AsyncWait` class variants may throw `std::alloc` if heap allocation 
-/// fails within `operator()(Args... args)`. All other delegate class functions do not throw 
-/// exceptions.
+/// The `Async` and `AsyncWait` class variants may throw `std::bad_alloc` if heap allocation 
+/// fails within `operator()(Args... args)`. Alternatively, define `USE_ASSERTS` to use `assert`
+/// as opposed to exceptions. All other delegate class functions do not throw exceptions.
 /// 
 /// Github responsitory location:  
 /// https://github.com/endurodave/cpp-async-delegate

Delegate/DelegateOpt.h

@@ -5,7 +5,7 @@
 /// @brief Delegate library options header file. 
 
 // Define this macro to switch between assert or exception handling
-//#define USE_ASSERTS  // Comment this out to use exceptions
+//#define USE_ASSERTS  // Comment this out to use asserts
 
 #ifdef USE_ASSERTS
     #include <cassert>