summaryrefslogtreecommitdiffstats
path: root/DOCS/man/input.rst
diff options
context:
space:
mode:
Diffstat (limited to 'DOCS/man/input.rst')
-rw-r--r--DOCS/man/input.rst36
1 files changed, 35 insertions, 1 deletions
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index 58e2b9c27d..6706fc3198 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -870,11 +870,45 @@ prefixes can be specified. They are separated by whitespace.
are asynchronous by default (or rather, their effects might manifest
after completion of the command). The semantics of this flag might change
in the future. Set it only if you don't rely on the effects of this command
- being fully realized when it returns.
+ being fully realized when it returns. See `Synchronous vs. Asynchronous`_.
+``sync``
+ Allow synchronous execution (if possible). Normally, all commands are
+ synchronous by default, but some are asynchronous by default for
+ compatibility with older behavior.
All of the osd prefixes are still overridden by the global ``--osd-level``
settings.
+Synchronous vs. Asynchronous
+----------------------------
+
+The ``async`` and ``sync`` prefix matter only for how the issuer of the command
+waits on the completion of the command. Normally it does not affect how the
+command behaves by itself. There are the following cases:
+
+- Normal input.conf commands are always run asynchronously. Slow running
+ commands are queued up or run in parallel.
+- "Multi" input.conf commands (1 key binding, concatenated with ``;``) will be
+ executed in order, except for commands that are async (either prefixed with
+ ``async``, or async by default for some commands). The async commands are
+ run in a detached manner, possibly in parallel to the remaining sync commands
+ in the list.
+- Normal Lua and libmpv commands (e.g. ``mpv_command()``) are run in a blocking
+ manner, unless the ``async`` prefix is used, or the command is async by
+ default. This means in the sync case the caller will block, even if the core
+ continues playback. Async mode runs the command in a detached manner.
+- Async libmpv command API (e.g. ``mpv_command_async()``) never blocks the
+ caller, and always notify their completion with a message. The ``sync`` and
+ ``async`` prefixes make no difference.
+- In all cases, async mode can still run commands in a synchronous manner, even
+ in detached mode. This can for example happen in cases when a command does not
+ have an asynchronous implementation. The async libmpv API still never blocks
+ the caller in these cases.
+
+The only exception is the current legacy behavior with screenshot commands,
+which will be fixed later. Using the ``async`` prefix makes them run the file
+saving code in a detached manner.
+
Input Sections
--------------