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.

1 files changed, 32 insertions, 3 deletions

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
 --------