docs/design/part-events.txt: Update some docs.

Original commit message from CVS:
* docs/design/part-events.txt:
Update some docs.
* docs/design/part-block.txt:
* gst/gstpad.c: (gst_pad_is_blocking), (handle_pad_block),
(gst_pad_push_event):
Revert BLOCKING patch, it tries to be smart without really having a
clear idea what or how. So, now we discard all FLUSHING events again on
a blocking pad. Should fix gnonlin again.

ChangeLog

@@ -1,3 +1,15 @@
+2006-10-23  Wim Taymans  <wim@fluendo.com>
+
+	* docs/design/part-events.txt:
+	Update some docs.
+
+	* docs/design/part-block.txt:
+	* gst/gstpad.c: (gst_pad_is_blocking), (handle_pad_block),
+	(gst_pad_push_event):
+	Revert BLOCKING patch, it tries to be smart without really having a
+	clear idea what or how. So, now we discard all FLUSHING events again on
+	a blocking pad. Should fix gnonlin again.
+
 2006-10-23  Wim Taymans  <wim@fluendo.com>
 
 	Patch by: Sergey Scobich <sergey dot scobich at gmail dot com>

docs/design/part-block.txt

@@ -69,19 +69,9 @@ Flushing
  is blocking somewhere downstream, the callback is not called or the sync block
  does not return.
 
- In order for the block to happen, a FLUSH_START needs to be:
+ In order for the block to happen, a FLUSH_START needs to be sent directly on
- _ either sent directly on the downstream blocking element/pad so that it
+ the downstream blocking element/pad so that it releases the stream lock, and it
-   release the stream lock, and it gives a chance for the elem1.src pad to
+ gives a chance for the elem1.src pad to block.
-   block.
- _ A FLUSH_START is sent downstream from an upstream element, causing all the
-   pads down to the blocking element/pad (including elem1.src) to go to the
-   FLUSHING state. A FLUSH_STOP can now be sent downstream, causing all the
-   pads down to the previously blocking element to unset their FLUSHING state.
-   The next push will then properly block on elem1.src.
-
- In this case, the pads have to be careful when handling the FLUSH events
- forwarding. Those events should only be forwarded downstream is the BLOCKED
- pad was previously BLOCKING.
 
 
 Use cases:

docs/design/part-events.txt

@@ -122,12 +122,12 @@ A NEWSEGMENT event should be generated as soon as possible in the pipeline and
 is usually generated by a demuxer or source. The event is generated before 
 pushing the first buffer and after a seek, right before pushing the new buffer.
 
-The NEWSEGMENT event can be sent from both the application and the streaming
+The NEWSEGMENT event should be sent from the streaming thread and should be
-thread and should be serialized with the buffers.
+serialized with the buffers.
 
 Buffers should be clipped within the range indicated by the newsegment event
-start and stop values. Sinks must to drop buffers with timestamps out
+start and stop values. Sinks must drop buffers with timestamps out of the
-of the indicated newsegment range.
+indicated newsegment range.
 
 If a newsegment arrives at an element not preceeded by a flush event, the 
 streamtime of the pipeline will not be reset to 0 so any element that syncs

gst/gstpad.c

@@ -1068,9 +1068,7 @@ gst_pad_is_blocking (GstPad * pad)
   g_return_val_if_fail (GST_IS_PAD (pad), result);
 
   GST_OBJECT_LOCK (pad);
-
   /* the blocking flag is only valid if the pad is not flushing */
-
   result = GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_BLOCKING) &&
       !GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_FLUSHING);
   GST_OBJECT_UNLOCK (pad);
@@ -3210,9 +3208,7 @@ gst_ghost_pad_save_thyself (GstPad * pad, xmlNodePtr parent)
  *   the pad block happens.
  *
  * During the actual blocking state, the GST_PAD_BLOCKING flag is set.
- * The GST_PAD_BLOCKING flag is unset when the pad was unblocked without a
+ * The GST_PAD_BLOCKING flag is unset when the pad was unblocked.
- * flush. This is to know whether the pad was blocking when GST_PAD_FLUSHING
- * was set.
  *
  * MT safe.
  */
@@ -3271,14 +3267,11 @@ handle_pad_block (GstPad * pad)
         "Waiting to be unblocked or set flushing");
     GST_OBJECT_FLAG_SET (pad, GST_PAD_BLOCKING);
     GST_PAD_BLOCK_WAIT (pad);
+    GST_OBJECT_FLAG_UNSET (pad, GST_PAD_BLOCKING);
 
-    /* see if we got unlocked by a flush or not */
+    /* see if we got unblocked by a flush or not */
     if (GST_PAD_IS_FLUSHING (pad))
       goto flushing;
-
-    /* If we made it here we were unblocked and not flushing, remove the
-     * blocking flag now. */
-    GST_OBJECT_FLAG_UNSET (pad, GST_PAD_BLOCKING);
   }
 
   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "got unblocked");
@@ -3880,10 +3873,12 @@ gst_pad_push_event (GstPad * pad, GstEvent * event)
     case GST_EVENT_FLUSH_START:
       GST_PAD_SET_FLUSHING (pad);
 
-      if (G_UNLIKELY (GST_PAD_IS_BLOCKING (pad))) {
+      if (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
         /* flush start will have set the FLUSHING flag and will then
          * unlock all threads doing a GCond wait on the blocking pad. This
          * will typically unblock the STREAMING thread blocked on a pad. */
+        GST_LOG_OBJECT (pad, "Pad is blocked, not forwarding flush-start, "
+            "doing block signal.");
         GST_PAD_BLOCK_SIGNAL (pad);
         goto flushed;
       }
@@ -3891,13 +3886,9 @@ gst_pad_push_event (GstPad * pad, GstEvent * event)
     case GST_EVENT_FLUSH_STOP:
       GST_PAD_UNSET_FLUSHING (pad);
 
-      /* If pad was blocking on something when the pad received flush-start, the 
+      /* if we are blocked, flush away the FLUSH_STOP event */
-       * BLOCKING flag was never cleared. we don't forward the flush-stop event
+      if (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
-       * either then but unset the blocking flag. */
+        GST_LOG_OBJECT (pad, "Pad is blocked, not forwarding flush-stop");
-      if (G_UNLIKELY (GST_PAD_IS_BLOCKING (pad))) {
-        GST_OBJECT_FLAG_UNSET (pad, GST_PAD_BLOCKING);
-        GST_LOG_OBJECT (pad,
-            "Pad was previously blocking, not forwarding flush-stop");
         goto flushed;
       }
       break;