From 50f38494104bf71ba426f5af5d4398e370440548 Mon Sep 17 00:00:00 2001
From: Benedikt Burger <67148916+bmoneke@users.noreply.github.com>
Date: Wed, 27 Sep 2023 11:16:32 +0200
Subject: [PATCH] Add locking actor.

---
 control_protocol.md        |  22 +++---
 schemas/locking_actor.json | 144 +++++++++++++++++++++++++++++++++++++
 2 files changed, 157 insertions(+), 9 deletions(-)
 create mode 100644 schemas/locking_actor.json

diff --git a/control_protocol.md b/control_protocol.md
index 9c972cf..e97d8e3 100644
--- a/control_protocol.md
+++ b/control_protocol.md
@@ -391,17 +391,12 @@ An {ref}`control_protocol.md#Actor`, which supports regular polling of values, M
 
 An {ref}`control_protocol.md#Actor` which support locking resources MUST offer the following methods.
 
-:::{note}
-TBD change the python code to json
+:::{data-viewer}
+:expand:
+:file: schemas/locking_actor.json
 :::
 
-::: python
-    def lock(self, resource: Optional[str] = None) -> bool: ...
-
-    def unlock(self, resource: Optional[str] = None) -> None: ...
-
-    def force_unlock(self, resource: Optional[str] = None) -> None: ...
-:::
+Accessing a locked resource (the whole Component or parts of it) or trying to unlock one, locked by another Component, will raise {ref}`control_protocol.md#locking_errors`.
 
 
 ### Errors
@@ -425,3 +420,12 @@ Their error codes are in the range of -32090 to -32099.
 | -32091 | The name is already taken.         | Name of the Component| A Component tries to sign in, but another Component is signed in with the same name  |
 | -32092 | Node is unknown.                   | Name of the Node     | The Node to which the message should be sent, is not known to this Coordinator.      |
 | -32093 | Receiver is not in addresses list. | Name of the receiver | The Component to which the message should be sent, is not known to this Coordinator. |
+
+
+#### Locking errors
+
+Errors related to locked Resources
+
+| code   | message          | data | description                                  |
+|--------|------------------|------|----------------------------------------------|
+| -32050 | Resource locked! | -    | The resource is locked by another component. |
diff --git a/schemas/locking_actor.json b/schemas/locking_actor.json
new file mode 100644
index 0000000..46e8259
--- /dev/null
+++ b/schemas/locking_actor.json
@@ -0,0 +1,144 @@
+{
+    "openrpc": "1.2.6",
+    "info": {
+        "title": "Locking Actor",
+        "version": "0.1.0"
+    },
+    "methods": [
+        {
+            "name": "lock",
+            "description": "Lock this Component or a resource of it, such that no other Component may use it.",
+            "params": [
+                {
+                    "name": "resource",
+                    "schema": {
+                            "type": "string"
+                    },
+                    "required": false
+                }
+            ],
+            "result": {
+                "name": "result",
+                "schema": {
+                    "type": "boolean",
+                    "description": "Whether locking succeeded or not."
+                },
+                "required": true
+            },
+            "examples": [
+                {
+                    "name": "Lock the 'channel1' resource of the Component",
+                    "params": [
+                        {
+                            "name": "resource",
+                            "value": "channel1"
+                        }
+                    ],
+                    "result": {
+                        "name": "result",
+                        "value": true
+                    }
+                },
+                {
+                    "name": "Lock Component example",
+                    "params": [
+                    ],
+                    "result": {
+                        "name": "result",
+                        "value": true
+                    }
+                }
+            ]
+        },
+        {
+            "name": "unlock",
+            "description": "Unlock this Component or a resource of it, such that other Component may use it again. Only the locking Component may unlock.",
+            "params": [
+                {
+                    "name": "resource",
+                    "schema": {
+                            "type": "string"
+                    },
+                    "required": false
+                }
+            ],
+            "result": {
+                "name": "result",
+                "schema": {
+                    "type": "boolean",
+                    "description": "Whether unlocking succeeded or not."
+                },
+                "required": true
+            },
+            "examples": [
+                {
+                    "name": "Unock the 'channel1' resource of the Component",
+                    "params": [
+                        {
+                            "name": "resource",
+                            "value": "channel1"
+                        }
+                    ],
+                    "result": {
+                        "name": "result",
+                        "value": true
+                    }
+                },
+                {
+                    "name": "Unlock Component example",
+                    "params": [
+                    ],
+                    "result": {
+                        "name": "result",
+                        "value": true
+                    }
+                }
+            ]
+        },
+        {
+            "name": "force_unlock",
+            "description": "Unock this Component or a resource of it, such that other Component may use it. This may be used even if someone else locked the resource.",
+            "params": [
+                {
+                    "name": "resource",
+                    "schema": {
+                            "type": "string"
+                    },
+                    "required": false
+                }
+            ],
+            "result": {
+                "name": "result",
+                "schema": {
+                    "type": "boolean",
+                    "description": "Whether force unlocking succeeded or not."
+                },
+                "required": true
+            },
+            "examples": [
+                {
+                    "name": "Force unlock the 'channel1' resource of the Component",
+                    "params": [
+                        {
+                            "name": "resource",
+                            "value": "channel1"
+                        }
+                    ],
+                    "result": {
+                        "name": "result",
+                        "value": true
+                    }
+                },
+                {
+                    "name": "Force unlock Component example",
+                    "params": [
+                    ],
+                    "result": {
+                        "name": "result",
+                        "value": true
+                    }
+                }
+            ]
+        }
+    ]
+}