Add blurb about how the bus goes into flushing mode and drops all messages when its...

Original commit message from CVS:
* docs/design/part-gstbin.txt:
* docs/design/part-gstbus.txt:
* gst/gstbus.c:
Add blurb about how the bus goes into flushing mode and
drops all messages when its bin goes from READY into NULL
state.

diff --git a/ChangeLog b/ChangeLog
index d7e8e87599906c822a20b1552166b24766b3b0dc..d0d9a4ad791a081a9d6de55487a9b8c2b86a70a4 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2005-09-23  Tim-Philipp Müller  <tim at centricular dot net>
+
+       * docs/design/part-gstbin.txt:
+       * docs/design/part-gstbus.txt:
+       * gst/gstbus.c:
+         Add blurb about how the bus goes into flushing mode and
+         drops all messages when its bin goes from READY into NULL 
+         state.
+
 2005-09-23  Thomas Vander Stichele  <thomas at apestaart dot org>
 
        * docs/gst/gstreamer-sections.txt:

diff --git a/docs/design/part-gstbin.txt b/docs/design/part-gstbin.txt
index eb3faa2095c6ed2d6f8e89278137e457e5d97a96..78486b2e87c45d83f03ea89b2955195ac8a14bc9 100644 (file)
--- a/docs/design/part-gstbin.txt
+++ b/docs/design/part-gstbin.txt
@@ -55,6 +55,13 @@ external message bus, except for EOS which is handled specially.
 The application can retrieve the external GstBus and integrate it in the
 mainloop or it can just _pop() messages off in its own thread.
 
+When a bin goes from READY into NULL state, it will set its bus to flushing, 
+ie. the bus will drop all existing and new messages on the bus. This is 
+necessary because bus messages hold references to the bin or its elements, 
+so there are circular references that need to be broken if one ever wants 
+to be able to destroy the bin properly. 
+
+
 EOS
 ---
 

diff --git a/docs/design/part-gstbus.txt b/docs/design/part-gstbus.txt
index 7396a69cc90300f89009d7aad44c3759ad153fb8..ba9d752125f0ca49952fee0f865f5a6937bb68df 100644 (file)
--- a/docs/design/part-gstbus.txt
+++ b/docs/design/part-gstbus.txt
@@ -27,3 +27,9 @@ possible to react to a message in the same thread that posted the
 message on the bus. This should only be used if the application is able
 to deal with messages from different threads.
 
+When a pipeline or bin goes from READY into NULL state, it will set its bus
+to flushing, ie. the bus will drop all existing and new messages on the bus,
+This is necessary because bus messages hold references to the bin/pipeline
+or its elements, so there are circular references that need to be broken if
+one ever wants to be able to destroy a bin or pipeline properly.
+

diff --git a/gst/gstbus.c b/gst/gstbus.c
index da464a6f4aa404428e63d69e35471f67cadd4c27..88881d849439f7dcf48841e1f594671945c59f53 100644 (file)
--- a/gst/gstbus.c
+++ b/gst/gstbus.c
@@ -53,6 +53,9 @@
  * to deal with messages from different threads.
  *
  * Every #GstBin has one bus.
+ *
+ * Note that a #GstBin will set its bus into flushing state when changing from
+ * READY to NULL state.
  */
 
 #include <errno.h>