From 1487b5072081d760a54180e16ba79fe848d00c46 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Tim-Philipp=20M=C3=BCller?= Date: Fri, 20 Jun 2008 10:20:08 +0000 Subject: [PATCH] gst/gstbus.c: Make it known that gst_bus_poll() is pure evil (fixes #538810). Original commit message from CVS: * gst/gstbus.c: Make it known that gst_bus_poll() is pure evil (fixes #538810). --- ChangeLog | 5 +++++ gst/gstbus.c | 20 +++++++++++++++++++- 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/ChangeLog b/ChangeLog index 3227f09..784a11a 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2008-06-20 Tim-Philipp Müller + + * gst/gstbus.c: + Make it known that gst_bus_poll() is pure evil (fixes #538810). + 2008-06-20 Stefan Kost * plugins/elements/gstcapsfilter.c: diff --git a/gst/gstbus.c b/gst/gstbus.c index c2a9093..73b4259 100644 --- a/gst/gstbus.c +++ b/gst/gstbus.c @@ -972,7 +972,8 @@ poll_destroy_timeout (GstBusPollData * poll_data) * @bus: a #GstBus * @events: a mask of #GstMessageType, representing the set of message types to * poll for. - * @timeout: the poll timeout, as a #GstClockTimeDiff, or -1 to poll indefinitely. + * @timeout: the poll timeout, as a #GstClockTimeDiff, or -1 to poll + * indefinitely. * * Poll the bus for messages. Will block while waiting for messages to come. * You can specify a maximum time to poll with the @timeout parameter. If @@ -989,6 +990,23 @@ poll_destroy_timeout (GstBusPollData * poll_data) * This function will run a main loop from the default main context when * polling. * + * You should never use this function, since it is pure evil. This is + * especially true for GUI applications based on Gtk+ or Qt, but also for any + * other non-trivial application that uses the GLib main loop. As this function + * runs a GLib main loop, any callback attached to the default GLib main + * context may be invoked. This could be timeouts, GUI events, I/O events etc.; + * even if gst_bus_poll() is called with a 0 timeout. Any of these callbacks + * may do things you do not expect, e.g. destroy the main application window or + * some other resource; change other application state; display a dialog and + * run another main loop until the user clicks it away. In short, using this + * function may add a lot of complexity to your code through unexpected + * re-entrancy and unexpected changes to your application's state. + * + * For 0 timeouts use gst_bus_pop_filtered() instead of this function; for + * other short timeouts use gst_bus_timed_pop_filtered(); everything else is + * better handled by setting up an asynchronous bus watch and doing things + * from there. + * * Returns: The message that was received, or NULL if the poll timed out. * The message is taken from the bus and needs to be unreffed with * gst_message_unref() after usage. -- 2.7.4