client API: add API function that ensures total destruction

mpv_destroy() should perhaps better be called mpv_detach(), because it
destroys only the handle, not necessarily the player. The player is only
terminated if a quit command is sent.

This function quits automatically, and additionally waits until the
player is completely destroyed. It removes the possibility that the
player core is still uninitializing, while all client handles are
already destroyed. (Although in practice, the difference is usually not
important.)

1 files changed, 18 insertions, 1 deletions

diff --git a/libmpv/client.h b/libmpv/client.h
index e5e6d5a3e8..d1fe312500 100644
--- a/libmpv/client.h
+++ b/libmpv/client.h
@@ -316,11 +316,28 @@ int mpv_initialize(mpv_handle *ctx);
  * Disconnect and destroy the client context. ctx will be deallocated with this
  * API call. This leaves the player running. If you want to be sure that the
  * player is terminated, send a "quit" command, and wait until the
- * MPV_EVENT_SHUTDOWN event is received.
+ * MPV_EVENT_SHUTDOWN event is received, or use mpv_terminate_destroy().
  */
 void mpv_destroy(mpv_handle *ctx);
 
 /**
+ * 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_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_destroy() is called somewhere on the way, it's not safe to call
+ * other functions concurrently on the same context.
+ *
+ * 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_destroy(),
+ * without waiting for the actual shutdown.
+ */
+void mpv_terminate_destroy(mpv_handle *ctx);
+
+/**
  * Load a config file. This loads and parses the file, and sets every entry in
  * the config file's default section as if mpv_set_option_string() is called.
  *