From b05550fe550cafb61cbb0214fb43d8bc93898ec0 Mon Sep 17 00:00:00 2001 From: wm4 Date: Mon, 24 Feb 2020 00:14:54 +0100 Subject: ipc: implement asynchronous commands I decided to make this explicit. The alternative would have been making all commands asynchronous always, like a small note in the manpage threatened. I think that could have caused compatibility issues. As a design decision, this does not send a reply if an async command started. This could be a good or bad idea, but in any case, it will make async command look almost like synchronous ones, except they don't block the IPC protocol. --- DOCS/man/ipc.rst | 35 ++++++++++++++++++++++++++++++++--- 1 file changed, 32 insertions(+), 3 deletions(-) (limited to 'DOCS') diff --git a/DOCS/man/ipc.rst b/DOCS/man/ipc.rst index 17bd373e2c..6d0f9c0d9c 100644 --- a/DOCS/man/ipc.rst +++ b/DOCS/man/ipc.rst @@ -136,9 +136,6 @@ Would generate this response: If you don't specify a ``request_id``, command replies will set it to 0. -Commands may run asynchronously in the future, instead of blocking the socket -until a reply is sent. - All commands, replies, and events are separated from each other with a line break character (``\n``). @@ -150,6 +147,38 @@ with ``#`` and empty lines are ignored. Currently, embedded 0 bytes terminate the current line, but you should not rely on this. +Asynchronous commands +--------------------- + +Command can be run asynchronously. This behaves exactly as with normal command +execution, except that execution is not blocking. Other commands can be sent +while it's executing, and command completion can be arbitrarily reordered. + +The ``async`` field controls this. If present, it must be a boolean. If missing, +``false`` is assumed. + +For example, this initiates an asynchronous command: + +:: + + { "command": ["screenshot"], "request_id": 123, "async": true } + +And this is the completion: + +:: + + {"request_id":123,"error":"success","data":null} + +By design, you will not get a confirmation that the command was started. If a +command is long running, sending the message will lead to any reply until much +later when the command finishes. + +Some commands execute synchronously, but these will behave like asynchronous +commands that finished execution immediately. + +Cancellation of asynchronous commands is available in the libmpv API, but has +not yet been implemented in the IPC protocol. + Commands -------- -- cgit v1.2.3