From 66373721d544fe1f1e765800d4daf9127a6ac694 Mon Sep 17 00:00:00 2001 From: Philippe Normand Date: Thu, 9 Nov 2023 17:57:22 +0000 Subject: [PATCH] gstplay: Add a minimal documentation header Also mentioning the need to set the bus to flushing state before disposing the player in order to avoid reference cycles. Fixes #3107 Part-of: --- girs/GstPlay-1.0.gir | 27 ++++++++++++++++++ .../playback/player/gst-play/gst-play.c | 6 ++++ .../gst-libs/gst/play/gstplay.c | 28 +++++++++++++++++++ 3 files changed, 61 insertions(+) diff --git a/girs/GstPlay-1.0.gir b/girs/GstPlay-1.0.gir index d6c2c93317..b4d2fc3d0f 100644 --- a/girs/GstPlay-1.0.gir +++ b/girs/GstPlay-1.0.gir @@ -306,6 +306,33 @@ and/or use gtk-doc annotations. --> + The goal of the GstPlay library is to ease the integration of multimedia +playback features in applications. Thus, if you need to build a media player +from the ground-up, GstPlay provides the features you will most likely need. + +An example player is available in gst-examples/playback/player/gst-play/. + +Internally the GstPlay makes use of the `playbin` element. `playbin3` can be +selected if the `GST_PLAY_USE_PLAYBIN3=1` environment variable has been set. + +**Important note**: In order to prevent the GstPlay object from leaking, its +GstBus should be set to flushing state before any attempt to drop the last +reference of the GstPlay object. An example in C: + +```c +... +GstBus *bus = gst_play_get_message_bus (player); +gst_bus_set_flushing (bus, TRUE); +gst_object_unref (bus); +gst_object_unref (player); +``` + +The messages managed by the player contain a reference to itself, and if the +bus watch is just removed together with dropping the player then the bus will +simply keep them around forever (and the bus never goes away because the +player has a strong reference to it, so there's a reference cycle as long as +there are messages). Setting the bus to flushing state forces it to get rid +of its queued messages, thus breaking any possible reference cycle. Creates a new #GstPlay instance. diff --git a/subprojects/gst-examples/playback/player/gst-play/gst-play.c b/subprojects/gst-examples/playback/player/gst-play/gst-play.c index 73755ffaa1..592df54a94 100644 --- a/subprojects/gst-examples/playback/player/gst-play/gst-play.c +++ b/subprojects/gst-examples/playback/player/gst-play/gst-play.c @@ -390,8 +390,14 @@ play_new (gchar ** uris, gdouble initial_volume) static void play_free (Player * play) { + GstBus *bus = NULL; + play_reset (play); + bus = gst_play_get_message_bus (play->player); + gst_bus_set_flushing (bus, TRUE); + gst_object_unref (bus); + g_clear_object (&play->signal_adapter); gst_object_unref (play->player); diff --git a/subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c b/subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c index 6c6653987a..015eb0123a 100644 --- a/subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c +++ b/subprojects/gst-plugins-bad/gst-libs/gst/play/gstplay.c @@ -28,6 +28,34 @@ * @symbols: * - GstPlay * + * The goal of the GstPlay library is to ease the integration of multimedia + * playback features in applications. Thus, if you need to build a media player + * from the ground-up, GstPlay provides the features you will most likely need. + * + * An example player is available in gst-examples/playback/player/gst-play/. + * + * Internally the GstPlay makes use of the `playbin` element. `playbin3` can be + * selected if the `GST_PLAY_USE_PLAYBIN3=1` environment variable has been set. + * + * **Important note**: In order to prevent the GstPlay object from leaking, its + * GstBus should be set to flushing state before any attempt to drop the last + * reference of the GstPlay object. An example in C: + * + * ```c + * ... + * GstBus *bus = gst_play_get_message_bus (player); + * gst_bus_set_flushing (bus, TRUE); + * gst_object_unref (bus); + * gst_object_unref (player); + * ``` + * + * The messages managed by the player contain a reference to itself, and if the + * bus watch is just removed together with dropping the player then the bus will + * simply keep them around forever (and the bus never goes away because the + * player has a strong reference to it, so there's a reference cycle as long as + * there are messages). Setting the bus to flushing state forces it to get rid + * of its queued messages, thus breaking any possible reference cycle. + * * Since: 1.20 */