From 95ab93d9f15f84271732bc785a72db846d2933dc Mon Sep 17 00:00:00 2001 From: wm4 Date: Sat, 5 May 2018 12:58:37 +0200 Subject: client API: some doxygen fixes/additions --- libmpv/client.h | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'libmpv/client.h') diff --git a/libmpv/client.h b/libmpv/client.h index 488ccb332c..d2a9ebfbac 100644 --- a/libmpv/client.h +++ b/libmpv/client.h @@ -195,6 +195,18 @@ extern "C" { * or change the underlying datatypes. It might be a good idea to prefer * MPV_FORMAT_STRING over other types to decouple your code from potential * mpv changes. + * + * Future changes + * -------------- + * + * This are the planned changes that will most likely be done on the next major + * bump of the library: + * + * - remove all symbols and include files that are marked as deprecated + * - reassign enum numerical values to remove gaps + * - remove the mpv_opengl_init_params.extra_exts field + * - change the type of mpv_event_end_file.reason + * - disabling all events by default */ /** @@ -1575,6 +1587,7 @@ typedef struct mpv_event { * MPV_EVENT_SET_PROPERTY_REPLY * MPV_EVENT_COMMAND_REPLY * MPV_EVENT_PROPERTY_CHANGE + * MPV_EVENT_HOOK */ uint64_t reply_userdata; /** @@ -1584,6 +1597,7 @@ typedef struct mpv_event { * MPV_EVENT_LOG_MESSAGE: mpv_event_log_message* * MPV_EVENT_CLIENT_MESSAGE: mpv_event_client_message* * MPV_EVENT_END_FILE: mpv_event_end_file* + * MPV_EVENT_HOOK: mpv_event_hook* * other: NULL * * Note: future enhancements might add new event structs for existing or new -- cgit v1.2.3 From 005d3bc81a86dddf458c0d19142815687a303877 Mon Sep 17 00:00:00 2001 From: wm4 Date: Thu, 10 May 2018 12:41:01 +0200 Subject: client API: clarify asynchronous call ordering non-guarantees Both asynchronous and synchronous calls used to be put into the core's dispatch queue. Also, asynchronous calls were actually synchronous, just without forcing a wait on the client's thread. This meant that both kinds of calls were always strictly ordered. A longer time ago, synchronous calls were changed to simply lock the core. This could possibly lead to reordering. Recently, some commands were changed to run on worker threads, which made the order even looser. Also remove another now incorrect doxygen comment regarding async commands. --- libmpv/client.h | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) (limited to 'libmpv/client.h') diff --git a/libmpv/client.h b/libmpv/client.h index d2a9ebfbac..b276c54390 100644 --- a/libmpv/client.h +++ b/libmpv/client.h @@ -107,8 +107,9 @@ extern "C" { * careful not accidentally interpret the mpv_event->reply_userdata if an * event is not a reply. (For non-replies, this field is set to 0.) * - * Currently, asynchronous calls are always strictly ordered (even with - * synchronous calls) for each client, although that may change in the future. + * Asynchronous calls may be reordered in arbitrarily with other synchronous + * and asynchronous calls. If you want a guaranteed order, you need to wait + * until asynchronous calls report completion before doing the next call. * * Multithreading * -------------- @@ -969,10 +970,6 @@ 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. - * * * Safe to be called from mpv render API threads. * * @param reply_userdata the value mpv_event.reply_userdata of the reply will -- cgit v1.2.3 From f0678afba010cfd13418641036309b3724cb9f66 Mon Sep 17 00:00:00 2001 From: wm4 Date: Thu, 10 May 2018 14:33:10 +0200 Subject: client API: add returning of data from async commands This was not done sooner out of laziness. --- libmpv/client.h | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) (limited to 'libmpv/client.h') diff --git a/libmpv/client.h b/libmpv/client.h index b276c54390..f9c9f3686b 100644 --- a/libmpv/client.h +++ b/libmpv/client.h @@ -223,7 +223,7 @@ extern "C" { * relational operators (<, >, <=, >=). */ #define MPV_MAKE_VERSION(major, minor) (((major) << 16) | (minor) | 0UL) -#define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(1, 101) +#define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(1, 102) /** * The API user is allowed to "#define MPV_ENABLE_DEPRECATED 0" before @@ -967,10 +967,11 @@ int mpv_command_string(mpv_handle *ctx, const char *args); * Same as mpv_command, but run the command asynchronously. * * Commands are executed asynchronously. You will receive a - * MPV_EVENT_COMMAND_REPLY event. (This event will also have an - * error code set if running the command failed.) + * MPV_EVENT_COMMAND_REPLY event. This event will also have an + * error code set if running the command failed. For commands that + * return data, the data is put into mpv_event_command.result. * - * * Safe to be called from mpv render API threads. + * Safe to be called from mpv render API threads. * * @param reply_userdata the value mpv_event.reply_userdata of the reply will * be set to (see section about asynchronous calls) @@ -985,8 +986,7 @@ int mpv_command_async(mpv_handle *ctx, uint64_t reply_userdata, * function is to mpv_command_node() what mpv_command_async() is to * mpv_command(). * - * See mpv_command_async() for details. Retrieving the result is not - * supported yet. + * See mpv_command_async() for details. * * Safe to be called from mpv render API threads. * @@ -1211,7 +1211,8 @@ typedef enum mpv_event_id { */ MPV_EVENT_SET_PROPERTY_REPLY = 4, /** - * Reply to a mpv_command_async() request. + * Reply to a mpv_command_async() or mpv_command_node_async() request. + * See also mpv_event and mpv_event_command. */ MPV_EVENT_COMMAND_REPLY = 5, /** @@ -1558,6 +1559,17 @@ typedef struct mpv_event_hook { uint64_t id; } mpv_event_hook; +// Since API version 1.102. +typedef struct mpv_event_command { + /** + * Result data of the command. Note that success/failure is signaled + * separately via mpv_event.error. This field is only for result data + * in case of success. Most commands leave it at MPV_FORMAT_NONE. Set + * to MPV_FORMAT_NONE on failure. + */ + mpv_node result; +} mpv_event_command; + typedef struct mpv_event { /** * One of mpv_event. Keep in mind that later ABI compatible releases might @@ -1595,6 +1607,7 @@ typedef struct mpv_event { * MPV_EVENT_CLIENT_MESSAGE: mpv_event_client_message* * MPV_EVENT_END_FILE: mpv_event_end_file* * MPV_EVENT_HOOK: mpv_event_hook* + * MPV_EVENT_COMMAND_REPLY* mpv_event_command* * other: NULL * * Note: future enhancements might add new event structs for existing or new -- cgit v1.2.3 From 1aae88b4879f40c68cebbdcd47895787ecdcdf68 Mon Sep 17 00:00:00 2001 From: wm4 Date: Sat, 12 May 2018 14:50:07 +0200 Subject: input: add glue code for named arguments Named arguments should make it easier to have long time compatibility, even if command arguments get added or removed. They're also much nicer for commands with a large number of arguments, especially if many arguments are optional. As of this commit, this can not be used, because there is no command yet which supports them. See the following commit. --- libmpv/client.h | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) (limited to 'libmpv/client.h') diff --git a/libmpv/client.h b/libmpv/client.h index f9c9f3686b..f7f7fada58 100644 --- a/libmpv/client.h +++ b/libmpv/client.h @@ -941,10 +941,25 @@ int mpv_command(mpv_handle *ctx, const char **args); * * Does not use OSD and string expansion by default. * - * @param[in] args mpv_node with format set to MPV_FORMAT_NODE_ARRAY; each entry - * is an argument using an arbitrary format (the format must be - * compatible to the used command). Usually, the first item is - * the command name (as MPV_FORMAT_STRING). + * The args argument can have one of the following formats: + * + * MPV_FORMAT_NODE_ARRAY: + * Positional arguments. Each entry is an argument using an arbitrary + * format (the format must be compatible to the used command). Usually, + * the first item is the command name (as MPV_FORMAT_STRING). The order + * of arguments is as documented in each command description. + * + * MPV_FORMAT_NODE_MAP: + * Named arguments. This requires at least an entry with the key "name" + * to be present, which must be a string, and contains the command name. + * The special entry "_flags" is optional, and if present, must be an + * array of strings, each being a command prefix to apply. All other + * entries are interpreted as arguments. They must use the argument names + * as documented in each command description. Currently, most commands do + * not support named arguments at all. + * + * @param[in] args mpv_node with format set to one of the values documented + * above (see there for details) * @param[out] result Optional, pass NULL if unused. If not NULL, and if the * function succeeds, this is set to command-specific return * data. You must call mpv_free_node_contents() to free it -- cgit v1.2.3 From e4fb23ed7de874bb2d05824d7edb84cfd1b21101 Mon Sep 17 00:00:00 2001 From: wm4 Date: Sat, 12 May 2018 18:46:37 +0200 Subject: command: add a way to abort asynchronous commands Many asynchronous commands are potentially long running operations, such as loading something from network or running a foreign process. Obviously it shouldn't just be possible for them to freeze the player if they don't terminate as expected. Also, there will be situations where you want to explicitly stop some of those operations explicitly. So add an infrastructure for this. Commands have to support this explicitly. The next commit uses this to actually add support to a command. --- libmpv/client.h | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) (limited to 'libmpv/client.h') diff --git a/libmpv/client.h b/libmpv/client.h index f7f7fada58..32c2d0a6e1 100644 --- a/libmpv/client.h +++ b/libmpv/client.h @@ -1013,6 +1013,38 @@ int mpv_command_async(mpv_handle *ctx, uint64_t reply_userdata, int mpv_command_node_async(mpv_handle *ctx, uint64_t reply_userdata, mpv_node *args); +/** + * Signal to all async requests with the matching ID to abort. This affects + * the following API calls: + * + * mpv_command_async + * mpv_command_node_async + * + * All of these functions take a reply_userdata parameter. This API function + * tells all requests with the matching reply_userdata value to try to return + * as soon as possible. If there are multiple requests with matching ID, it + * aborts all of them. + * + * This API function is mostly asynchronous itself. It will not wait until the + * command is aborted. Instead, the command will terminate as usual, but with + * some work not done. How this is signaled depends on the specific command (for + * example, the "subprocess" command will indicate it by "killed_by_us" set to + * true in the result). How long it takes also depends on the situation. The + * aborting process is completely asynchronous. + * + * Not all commands may support this functionality. In this case, this function + * will have no effect. The same is true if the request using the passed + * reply_userdata has already terminated, has not been started yet, or was + * never in use at all. + * + * You have to be careful of race conditions: the time during which the abort + * request will be effective is _after_ e.g. mpv_command_async() has returned, + * and before the command has signaled completion with MPV_EVENT_COMMAND_REPLY. + * + * @param reply_userdata ID of the request to be aborted (see above) + */ +void mpv_abort_async_command(mpv_handle *ctx, uint64_t reply_userdata); + /** * Set a property to a given value. Properties are essentially variables which * can be queried or set at runtime. For example, writing to the pause property -- cgit v1.2.3 From 332907e1d7225ae39565d462aac5c45c3a5cad97 Mon Sep 17 00:00:00 2001 From: wm4 Date: Thu, 17 May 2018 20:10:39 +0200 Subject: command: give named arguments to almost all commands Before this change, only 1 command or so had named arguments. There is no reason why other commands can't have them, except that it's a bit of work to add them. Commands with variable number of arguments are inherently incompatible to named arguments, such as the "run" command. They still have dummy names, but obviously you can't assign multiple values to a single named argument (unless the argument has an array type, which would be something different). For now, disallow using named argument APIs with these commands. This might change later. 2 commands are adjusted to not need a separate default value by changing flag constants. (The numeric values are C only and can't be set by users.) Make the command syntax in the manpage more consistent. Now none of the allowed choice/flag names are in the command header, and all arguments are shown with their proper name and quoted with <...>. Some places in the manpage and the client.h doxygen are updated to reflect that most commands support named arguments. In addition, try to improve the documentation of the syntax and need for escaping etc. as well. (Or actually most uses of the word "argument" should be "parameter".) --- libmpv/client.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'libmpv/client.h') diff --git a/libmpv/client.h b/libmpv/client.h index 32c2d0a6e1..44c48402a8 100644 --- a/libmpv/client.h +++ b/libmpv/client.h @@ -955,8 +955,8 @@ int mpv_command(mpv_handle *ctx, const char **args); * The special entry "_flags" is optional, and if present, must be an * array of strings, each being a command prefix to apply. All other * entries are interpreted as arguments. They must use the argument names - * as documented in each command description. Currently, most commands do - * not support named arguments at all. + * as documented in each command description. Some commands do not + * support named arguments at all, and must use MPV_FORMAT_NODE_ARRAY. * * @param[in] args mpv_node with format set to one of the values documented * above (see there for details) -- cgit v1.2.3