From 4d9c6ab6b9b9c5436f5ee52f56aee304da4b20b1 Mon Sep 17 00:00:00 2001 From: wm4 Date: Fri, 9 Mar 2018 06:05:50 +0100 Subject: client API: rename mpv_detach_destroy() to mpv_destroy() Since this has clearer semantics now, the old name is just clunky and confusing. --- DOCS/client-api-changes.rst | 2 ++ libmpv/client.h | 28 +++++++++++++++++++++------- libmpv/mpv.def | 1 + player/client.c | 7 ++++++- 4 files changed, 30 insertions(+), 8 deletions(-) diff --git a/DOCS/client-api-changes.rst b/DOCS/client-api-changes.rst index 9b964da59a..5c3d6af7c5 100644 --- a/DOCS/client-api-changes.rst +++ b/DOCS/client-api-changes.rst @@ -37,6 +37,8 @@ API changes changes subtly (see documentation in the header file). In particular, mpv_detach_destroy() will not leave the player running in all situations anymore (it gets closer to refcounting). + - rename mpv_detach_destroy() to mpv_destroy() (the old function will + remain valid as deprecated alias) - add mpv_create_weak_client(), which makes use of above changes 1.28 - deprecate the render opengl_cb API, and replace it with render.h and render_gl.h. The goal is allowing support for APIs other than diff --git a/libmpv/client.h b/libmpv/client.h index 335e1417bc..acdac45dc5 100644 --- a/libmpv/client.h +++ b/libmpv/client.h @@ -451,6 +451,19 @@ int mpv_initialize(mpv_handle *ctx); * Disconnect and destroy the mpv_handle. ctx will be deallocated with this * API call. * + * If the last mpv_handle is detached, the core player is destroyed. In + * addition, if there are only weak mpv_handles (such as created by + * mpv_create_weak_client() or internal scripts), these mpv_handles will + * be sent MPV_EVENT_SHUTDOWN. This function may block until these clients + * have responded to the shutdown event, and the core is finally destroyed. + */ +void mpv_destroy(mpv_handle *ctx); + +#if MPV_ENABLE_DEPRECATED +/** + * @deprecated use mpv_destroy(), which has exactly the same semantics (the + * deprecation is a mere rename) + * * Since mpv client API version 1.29: * If the last mpv_handle is detached, the core player is destroyed. In * addition, if there are only weak mpv_handles (such as created by @@ -464,16 +477,17 @@ int mpv_initialize(mpv_handle *ctx); * MPV_EVENT_SHUTDOWN event is received, or use mpv_terminate_destroy(). */ void mpv_detach_destroy(mpv_handle *ctx); +#endif /** - * Similar to mpv_detach_destroy(), but brings the player and all clients down + * Similar to mpv_destroy(), but brings the player and all clients down * as well, and waits until all of them are destroyed. This function blocks. The - * advantage over mpv_detach_destroy() is that while mpv_detach_destroy() merely + * advantage over mpv_destroy() is that while mpv_destroy() merely * detaches the client handle from the player, this function quits the player, * waits until all other clients are destroyed (i.e. all mpv_handles are * detached), and also waits for the final termination of the player. * - * Since mpv_detach_destroy() is called somewhere on the way, it's not safe to + * Since mpv_destroy() is called somewhere on the way, it's not safe to * call other functions concurrently on the same context. * * Since mpv client API version 1.29: @@ -488,7 +502,7 @@ void mpv_detach_destroy(mpv_handle *ctx); * Before mpv client API version 1.29: * If this is called on a mpv_handle that was not created with mpv_create(), * this function will merely send a quit command and then call - * mpv_detach_destroy(), without waiting for the actual shutdown. + * mpv_destroy(), without waiting for the actual shutdown. */ void mpv_terminate_destroy(mpv_handle *ctx); @@ -498,7 +512,7 @@ void mpv_terminate_destroy(mpv_handle *ctx); * mpv_request_log_messages() state, its own set of observed properties, and * its own state for asynchronous operations. Otherwise, everything is shared. * - * This handle should be destroyed with mpv_detach_destroy() if no longer + * This handle should be destroyed with mpv_destroy() if no longer * needed. The core will live as long as there is at least 1 handle referencing * it. Any handle can make the core quit, which will result in every handle * receiving MPV_EVENT_SHUTDOWN. @@ -527,7 +541,7 @@ mpv_handle *mpv_create_client(mpv_handle *ctx, const char *name); * asked to terminate as well.) * * Note if you want to use this like refcounting: you have to be aware that - * mpv_terminate_destroy() _and_ mpv_detach_destroy() for the last non-weak + * mpv_terminate_destroy() _and_ mpv_destroy() for the last non-weak * mpv_handle will block until all weak mpv_handles are destroyed. */ mpv_handle *mpv_create_weak_client(mpv_handle *ctx, const char *name); @@ -1154,7 +1168,7 @@ typedef enum mpv_event_id { * to disconnect all clients. Most requests to the player will fail, and * mpv_wait_event() will always return instantly (returning new shutdown * events if no other events are queued). The client should react to this - * and quit with mpv_detach_destroy() as soon as possible. + * and quit with mpv_destroy() as soon as possible. */ MPV_EVENT_SHUTDOWN = 1, /** diff --git a/libmpv/mpv.def b/libmpv/mpv.def index 202f2071f0..ccd98422a7 100644 --- a/libmpv/mpv.def +++ b/libmpv/mpv.def @@ -8,6 +8,7 @@ mpv_command_string mpv_create mpv_create_client mpv_create_weak_client +mpv_destroy mpv_detach_destroy mpv_error_string mpv_event_name diff --git a/player/client.c b/player/client.c index d347033fe5..289508447b 100644 --- a/player/client.c +++ b/player/client.c @@ -468,11 +468,16 @@ static void mp_destroy_client(mpv_handle *ctx, bool terminate) } } -void mpv_detach_destroy(mpv_handle *ctx) +void mpv_destroy(mpv_handle *ctx) { mp_destroy_client(ctx, false); } +void mpv_detach_destroy(mpv_handle *ctx) +{ + mpv_destroy(ctx); +} + void mpv_terminate_destroy(mpv_handle *ctx) { mp_destroy_client(ctx, true); -- cgit v1.2.3