Add locking actor.

pymeasure · Sep 27, 2023 · 50f3849 · 50f3849
1 parent 9d9a6d7
commit 50f3849
Show file tree

Hide file tree

Showing 2 changed files with 157 additions and 9 deletions.
diff --git 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
@@ -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
+                    }
+                }
+            ]
+        }
+    ]
+}