Add blurb about how the bus goes into flushing mode and drops all messages when its bin goes from READY into NULL state.

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.

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:

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
 ---
 

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.
+

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>