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 ++++++++++++++++++++++++++++++++ libmpv/mpv.def | 1 + 2 files changed, 33 insertions(+) (limited to 'libmpv') 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 diff --git a/libmpv/mpv.def b/libmpv/mpv.def index b74378c4ae..5b1c2423ff 100644 --- a/libmpv/mpv.def +++ b/libmpv/mpv.def @@ -1,3 +1,4 @@ +mpv_abort_async_command mpv_client_api_version mpv_client_name mpv_command -- cgit v1.2.3