diff options
authorwm4 <wm4@nowhere>2018-03-09 06:05:50 +0100
committerKevin Mitchell <>2018-03-15 00:00:04 -0700
commit4d9c6ab6b9b9c5436f5ee52f56aee304da4b20b1 (patch)
parenta7f3cf473707b19bff9ea80b227490c8b305b601 (diff)
client API: rename mpv_detach_destroy() to mpv_destroy()
Since this has clearer semantics now, the old name is just clunky and confusing.
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);
+ * @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);
- * 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
@@ -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.
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
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);