input: add "async" flag

Obviously, this has no effect on commands which do not support this
explicitly. A later commit will enable this for screenshots.

Also add some wording on mpv_command_async(), which has nothing to do
with this. Having a more elegant, unified behavior would be nice. But
the API function was not created for this - it's merely for running
commands _synchronously_ on the core, but without blocking the client
API caller (if the API user consistently uses only async functions).

DOCS/man/input.rst

@@ -826,6 +826,12 @@ prefixes can be specified. They are separated by whitespace.
 ``repeatable``
     For some commands, keeping a key pressed doesn't run the command repeatedly.
     This prefix forces enabling key repeat in any case.
+``async``
+    Allow asynchronous execution (if possible). Note that only a few commands
+    will support this (usually this is explicitly documented). Some commands
+    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
 
 All of the osd prefixes are still overridden by the global ``--osd-level``
 settings.

input/cmd_parse.c

@@ -49,6 +49,7 @@ static const struct flag cmd_flags[] = {
     {"expand-properties",   0,               MP_EXPAND_PROPERTIES},
     {"raw",                 MP_EXPAND_PROPERTIES, 0},
     {"repeatable",          0,               MP_ALLOW_REPEAT},
+    {"async",               0,               MP_ASYNC_CMD},
     {0}
 };
 

input/input.h

@@ -34,6 +34,7 @@ enum mp_cmd_flags {
     MP_ON_OSD_MSG = 4,          // force a message, if applicable
     MP_EXPAND_PROPERTIES = 8,   // expand strings as properties
     MP_ALLOW_REPEAT = 16,       // if used as keybinding, allow key repeat
+    MP_ASYNC_CMD = 32,
 
     MP_ON_OSD_FLAGS = MP_ON_OSD_NO | MP_ON_OSD_AUTO |
                       MP_ON_OSD_BAR | MP_ON_OSD_MSG,

libmpv/client.h

@@ -879,6 +879,10 @@ int mpv_command_string(mpv_handle *ctx, const char *args);
  * MPV_EVENT_COMMAND_REPLY event. (This event will also have an
  * error code set if running the command failed.)
  *
+ * This has nothing to do with the "async" command prefix, although they might
+ * be unified in the future. For now, calling this API means that the command
+ * will be synchronously executed on the core, without blocking the API user.
+ *
  * @param reply_userdata the value mpv_event.reply_userdata of the reply will
  *                       be set to (see section about asynchronous calls)
  * @param args NULL-terminated list of strings (see mpv_command())