mod: BridgeClass rem unsafe get error methods

mod: tcp_client and monitor use RpcResult async calls to get errors
examples: Bridge test.ino with python code
doc: impr Bridge call examples new API

Author: eigen-value

README.md

@@ -5,7 +5,8 @@ In this repo it will be implemented an Arduino library wrapper for RPClite to be
 Including Arduino_RouterBridge.h gives the user access to a Bridge object that can be used both as a RPC client and/or server to execute and serve RPCs to/from the CPU Host running a GOLANG router.
 
 - The Bridge object is pre-defined on Serial1 and automatically initialized inside the main setup()
-- The Bridge.call method is blocking and works the same as in RPClite
+- The Bridge.call method is non-blocking and returns a RpcResult async object
+- RpcResult class implements a blocking .result method that waits for the RPC response and returns true if the RPC returned with no errors
 - The Bridge can provide callbacks to incoming RPC requests both in a thread-unsafe and thread-safe fashion (provide & provide_safe)
 - Thread-safe methods execution is granted in the main loop thread where update_safe is called. By design users cannot access .update_safe() freely
 - Thread-unsafe methods are served in an update callback, whose execution is granted in a separate thread. Nonetheless users can access .update() freely with caution
@@ -27,7 +28,7 @@ void setup() {
 
     Bridge.begin();
     Monitor.begin();
-    
+
     pinMode(LED_BUILTIN, OUTPUT);
 
     if (!Bridge.provide("set_led", set_led)) {
@@ -41,27 +42,33 @@ void setup() {
 }
 
 void loop() {
-    float res;
-    if (!Bridge.call("multiply", 1.0, 2.0).result(res)) {
-        Monitor.println("Error calling method: multiply");
-        Monitor.println(Bridge.get_error_code());
-        Monitor.println(Bridge.get_error_message());
+    float sum;
+
+    // CALL EXAMPLES
+
+    // Standard chained call: Bridge.call("method", params...).result(res)
+    if (!Bridge.call("add", 1.0, 2.0).result(sum)) {
+        Monitor.println("Error calling method: add");
+    };
+
+    // Async call
+    RpcResult async_rpc = Bridge.call("add", 3.0, 4.5);
+    if (!async_rpc.result(sum)) {
+        Monitor.println("Error calling method: add");
+        Monitor.print("Error code: ");
+        Monitor.println(async_rpc.error.code);
+        Monitor.print("Error message: ");
+        Monitor.println(async_rpc.error.traceback);
+    }
+
+    // Implicit boolean cast. Use with caution as in this case the call is indeed
+    // executed expecting a fallback nil result (MsgPack::object::nil_t)
+    if (!Bridge.call("send_greeting", "Hello Friend")) {
+        Monitor.println("Error calling method: send_greeting");
     };
 
+    // Please use notify when no reult (None, null, void, nil etc.) is expected from the opposite side
+    // the following is executed immediately
     Bridge.notify("signal", 200);
 }
 ```
-
-## Best practices ##
-Avoid catching Bridge call RpcResult without invoking its .result right away
-```cpp
-// OK
-float out;
-RpcResult res = Bridge.call("multiply", 1.0, 2.0);
-res.result(out);
-Monitor.println("TEST");
-
-// NOT OK
-//RpcResult res = Bridge.call("multiply", 1.0, 2.0);
-//Monitor.println("TEST");
-```

examples/test/python/main.py

@@ -0,0 +1,39 @@
+import time
+from arduino.app_utils import *
+
+
+def no_args_no_result():
+    print("0 args no result")
+    return
+
+def no_args_bool_result():
+    print("0 args bool result")
+    return True
+
+def one_args_float_result(a):
+    print("1 args float result")
+    return a^2
+
+def two_args_float_result(a, b):
+    print("2 args float result")
+    return a/b
+
+def one_args_no_result(msg: str):
+    print("1 args no result")
+    print(f"Message received: {msg}")
+
+def two_args_no_result(msg: str, x: int):
+    print("2 args no result")
+    print(f"Message received: {msg} {str(x)}")
+
+
+if __name__ == "__main__":
+
+    Bridge.provide("0_args_no_result", no_args_no_result)
+    Bridge.provide("0_args_bool_result", no_args_bool_result)
+    Bridge.provide("1_args_float_result", one_args_float_result)
+    Bridge.provide("2_args_float_result", two_args_float_result)
+    Bridge.provide("1_args_no_result", one_args_no_result)
+    Bridge.provide("2_args_no_result", two_args_no_result)
+
+    App.run()

examples/test/server_test

@@ -9,18 +9,6 @@
     
 */
 
-// to run this test example, launch server_test in a shell and then this sketch
-
-
-/* available registers 
-    register("ping")
-    register("0_args_no_result")
-    register("1_args_no_result")
-    register("2_args_no_result")
-    register("0_args_bool_result")
-    register("1_args_bool_result")
-    register("2_args_bool_result")
-*/
 
 #include "Arduino_RouterBridge.h"
 
@@ -42,7 +30,7 @@ void loop() {
     Bridge.call("0_args_no_result");
 
     if (Bridge.call("0_args_no_result")){
-      Monitor.println("0_args_no_result TRUE without result");                    // return true because no result
+      Monitor.println("0_args_no_result TRUE without result"); // returns true because there's no result
     }
     else{
       Monitor.println("0_args_no_result FALSE without result");
@@ -52,34 +40,63 @@ void loop() {
       Monitor.println("0_args_bool_result TRUE without result");
     }
     else{
-      Monitor.println("0_args_bool_result FALSE without result");                // return false because you need check the result
+      Monitor.println("0_args_bool_result FALSE without result"); // returns false -> check the result
     }
 
-    x=false;
+    x = false;
     if (Bridge.call("0_args_bool_result").result(x)){
-      Monitor.println("0_args_bool_result TRUE with result: "+String(x));                       // return true - the perfect call
+      Monitor.println("0_args_bool_result TRUE with result: "+String(x)); // returns true - the perfect call
     }
     else{
       Monitor.println("0_args_bool_result FALSE witt result: "+String(x));
     }
 
     int y = -1;
     if (Bridge.call("0_args_bool_result").result(y)){
-      Monitor.println("0_args_bool_result TRUE with result: "+String(y)+" (wrong result type)");                       // return true - the perfect call
+      Monitor.println("0_args_bool_result TRUE with result: "+String(y)+" (wrong result type)");
     }
-    else{
-      Monitor.println("0_args_bool_result FALSE with result: "+String(y)+" (wrong result type)");
+    else {
+      Monitor.println("0_args_bool_result FALSE with result: "+String(y)+" (wrong result type)"); // returns false - wrong type
     }
 
+    float pow;
+    RpcResult async_res = Bridge.call("1_args_float_result", 2.0, 3.0);  // passing 2 args to a function expecting 1
+    if (async_res.result(pow)) {
+      Monitor.println("Result of assignment and then result: "+String(pow)); // returns true, so the right result
+    } else {
+      Monitor.println("Error code: "+String(async_res.error.code));
+      Monitor.println("Error message: "+async_res.error.traceback);
+    }
 
-    // avoid to do followings
+    float div = 0;
+    RpcResult async_res1 = Bridge.call("2_args_float_result", 2.0);  // passing 1 arg when 2 are expected
+    if (async_res1.result(div)) {
+      Monitor.println("Result of assignment and then result: "+String(div)); // returns true, so the right result
+    } else {
+      Monitor.println("Error code: "+String(async_res1.error.code));
+      Monitor.println("Error message: "+async_res1.error.traceback);
+    }
+
+    div = 0;
+    RpcResult async_res2 = Bridge.call("2_args_float_result", 2.0, "invalid");  // passing a wrong type arg
+    if (async_res2.result(div)) {
+      Monitor.println("Result of assignment and then result: "+String(div)); // returns true, so the right result
+    } else {
+      Monitor.println("Error code: "+String(async_res2.error.code));
+      Monitor.println("Error message: "+async_res2.error.traceback);
+    }
 
-    RpcResult result = Bridge.call("0_args_bool_result");    // the call happens but you won't get the result
+    x = false;
+    RpcResult async_res3 = Bridge.call("0_args_bool_result");
+    if (async_res3.result(x)) {
+        Monitor.println("Result of assignment and then result: "+String(x)); // returns true, so the right result
+    } else {
+        Monitor.println("Error expecting bool result: "+String(async_res3.error.code));
+    }
 
-    bool x = false;
-    RpcResult result2 = Bridge.call("0_args_bool_result"); 
-    result2.result(x);
-    Monitor.println("Result of assignment and then result: "+String(x));                   // return true, so the right result
+    // Avoid the following:
+    // the call happens in the destructor falling back to the "no_result" case (a type mismatch here)
+    RpcResult async_res4 = Bridge.call("0_args_bool_result");
 
     delay(1000);
 }

examples/test/test.ino

@@ -32,10 +32,6 @@ void updateEntryPoint(void *, void *, void *);
 template<typename... Args>
 class RpcResult {
 
-private:
-    std::tuple<Args...> callback_params;
-    MsgPack::str_t method;
-
 public:
     RpcError error;
 
@@ -92,10 +88,13 @@ class RpcResult {
 
 private:
     uint32_t msg_id_wait{};
-    RPCClient* client;
     bool _executed = false;
+
+    MsgPack::str_t method;
+    RPCClient* client;
     struct k_mutex* read_mutex;
     struct k_mutex* write_mutex;
+    std::tuple<Args...> callback_params;
 };
 
 class BridgeClass {
@@ -206,8 +205,6 @@ class BridgeClass {
        return RpcResult<Args...>(method, client, &read_mutex, &write_mutex, std::forward<Args>(args)...);
     }
 
-
-
     template<typename... Args>
     void notify(const MsgPack::str_t method, Args&&... args)  {
         while (true) {
@@ -220,18 +217,6 @@ class BridgeClass {
         }
     }
 
-    String get_error_message() const {
-        return static_cast<String>(client->lastError.traceback);
-    }
-
-    uint8_t get_error_code() const {
-        return static_cast<uint8_t>(client->lastError.code);
-    }
-
-    RpcError& get_last_client_error() const {
-        return client->lastError;
-    }
-
 private:
 
     void update_safe() {

src/bridge.h

@@ -122,7 +122,9 @@ class BridgeMonitor: public Stream {
         if (size == 0) return;
 
         MsgPack::arr_t<uint8_t> message;
-        bool ret = bridge->call(MON_READ_METHOD, size).result(message);
+        RpcResult async_rpc = bridge->call(MON_READ_METHOD, size);
+
+        const bool ret = async_rpc.result(message);
 
         if (ret) {
             k_mutex_lock(&monitor_mutex, K_FOREVER);
@@ -132,7 +134,7 @@ class BridgeMonitor: public Stream {
             k_mutex_unlock(&monitor_mutex);
         }
 
-        // if (bridge.lastError.code > NO_ERR) {
+        // if (async_rpc.error.code > NO_ERR) {
         //     is_connected = false;
         // }
     }

src/monitor.h

@@ -198,15 +198,17 @@ class BridgeTCPClient : public Client {
         k_mutex_lock(&client_mutex, K_FOREVER);
 
         MsgPack::arr_t<uint8_t> message;
-        const bool ret = bridge->call(TCP_READ_METHOD, connection_id, size).result(message);
+        RpcResult async_rpc = bridge->call(TCP_READ_METHOD, connection_id, size);
+
+        const bool ret = async_rpc.result(message);
 
         if (ret) {
             for (size_t i = 0; i < message.size(); ++i) {
                 temp_buffer.store_char(static_cast<char>(message[i]));
             }
         }
 
-        if (bridge->get_last_client_error().code > NO_ERR) {
+        if (async_rpc.error.code > NO_ERR) {
             _connected = false;
         }