From 69ca3f3282783ea6b8f49871b733f89d7bfb9478 Mon Sep 17 00:00:00 2001
From: Niklas Kapelle <niklas@kapelle.org>
Date: Thu, 21 Mar 2024 00:22:53 +0100
Subject: [PATCH] added RPC to Concepts

---
 doc/Concepts.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/doc/Concepts.md b/doc/Concepts.md
index ae1c5f5..0d21433 100644
--- a/doc/Concepts.md
+++ b/doc/Concepts.md
@@ -156,3 +156,55 @@ TurtleMutex.runInTThread(() -> {
     }
 });
 ```
+
+# RPC
+
+With the help of dark and badly documented magic also known as "macros", we can create quickly create remote procedure call Classes to call functions on other 
+computers. A problem that arises is that since all data gets send over the network that we kinda lose the type safty. We cloud trust ourself to cast 
+the result of the request to the right type or we cloud just make use of macros. The RPC macro will create a RPC class that implements all functions of an 
+interface just that the return type is wrapped in a Promise. Now if we call a function of that RPC class it fires a request to the other computer and waits 
+for a response. On the other side the service makes use of that generated package handle function for the RPC class. 
+
+A simple example:
+
+```haxe
+interface IExampleRPC {
+	function addNumber(a:Int, b:Int):Int;
+}
+
+@:build(macros.rpc.RPC.buildRPC(IExampleRPC))
+class ExampleRPC extends RPCBase {}
+
+
+@:build(macros.Binstore.includeBin("Example SRV", ["example-srv"]))
+class ExampleService implements IProcess implements IExampleRPC {
+	private var handle:ProcessHandle;
+
+	public function new() {}
+
+	public function run(handle:ProcessHandle) {
+		this.handle = handle;
+
+		kernel.net.Net.registerProto("example", (pack) -> {
+			ExampleRPC.handlePackage(this, pack);
+		});
+	}
+
+	public function addNumber(a:Int, b:Int):Int {
+		return a + b;
+	}
+}
+
+// ...
+
+var rpc = new ExampleRPC(12,"example");
+
+rpc.addNumber(3,7).handle((p)->{
+    switch p {
+        case Success(r):
+            Log.info('3+7=$r');
+        case Failure(err):
+            Log.error('Error: $err');
+    }
+});
+```