events: Implement the stream-group-done event

A new event which precedes EOS in situations where we
need downstream to unblock any pads waiting on a stream
before we can send EOS. E.g, decodebin draining a chain
so it can switch pads.

https://bugzilla.gnome.org/show_bug.cgi?id=768995

5 files changed, 69 insertions, 3 deletions

diff --git a/gst/gstevent.c b/gst/gstevent.c
index 71e1884ad7..e691dfb97d 100644
--- a/gst/gstevent.c
+++ b/gst/gstevent.c
@@ -130,6 +130,7 @@ static GstEventQuarks event_quarks[] = {
   {GST_EVENT_CUSTOM_DOWNSTREAM_STICKY, "custom-downstream-sticky", 0},
   {GST_EVENT_CUSTOM_BOTH, "custom-both", 0},
   {GST_EVENT_CUSTOM_BOTH_OOB, "custom-both-oob", 0},
+  {GST_EVENT_STREAM_GROUP_DONE, "stream-group-done", 0},
 
   {0, NULL, 0}
 };
@@ -653,6 +654,57 @@ gst_event_parse_select_streams (GstEvent * event, GList ** streams)
 
 
 /**
+ * gst_event_new_stream_group_done:
+ * @group_id: the group id of the stream group which is ending
+ *
+ * Create a new Stream Group Done event. The stream-group-done event can
+ * only travel downstream synchronized with the buffer flow. Elements
+ * that receive the event on a pad should handle it mostly like EOS,
+ * and emit any data or pending buffers that would depend on more data
+ * arriving and unblock, since there won't be any more data.
+ *
+ * This event is followed by EOS at some point in the future, and is
+ * generally used when switching pads - to unblock downstream so that
+ * new pads can be exposed before sending EOS on the existing pads.
+ *
+ * Returns: (transfer full): the new stream-group-done event.
+ *
+ * Since: 1.10
+ */
+GstEvent *
+gst_event_new_stream_group_done (guint group_id)
+{
+  GstStructure *s;
+
+  s = gst_structure_new_id (GST_QUARK (EVENT_STREAM_GROUP_DONE),
+      GST_QUARK (GROUP_ID), G_TYPE_UINT, group_id, NULL);
+
+  return gst_event_new_custom (GST_EVENT_STREAM_GROUP_DONE, s);
+}
+
+/**
+ * gst_event_parse_stream_group_done:
+ * @event: a stream-group-done event.
+ * @group_id: (out): address of variable to store the group id into
+ *
+ * Parse a stream-group-done @event and store the result in the given
+ * @group_id location.
+ *
+ * Since: 1.10
+ */
+void
+gst_event_parse_stream_group_done (GstEvent * event, guint * group_id)
+{
+  g_return_if_fail (event != NULL);
+  g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_STREAM_GROUP_DONE);
+
+  if (group_id) {
+    gst_structure_id_get (GST_EVENT_STRUCTURE (event),
+        GST_QUARK (GROUP_ID), G_TYPE_UINT, group_id, NULL);
+  }
+}
+
+/**
  * gst_event_new_eos:
  *
  * Create a new EOS event. The eos event can only travel downstream
diff --git a/gst/gstevent.h b/gst/gstevent.h
index faf0014805..e7dbb25c4d 100644
--- a/gst/gstevent.h
+++ b/gst/gstevent.h
@@ -95,6 +95,9 @@ typedef enum {
  * @GST_EVENT_SINK_MESSAGE: An event that sinks turn into a message. Used to
  *                          send messages that should be emitted in sync with
  *                          rendering.
+ * @GST_EVENT_STREAM_GROUP_DONE: Indicates that there is no more data for
+ *                 the stream group ID in the message. Sent before EOS
+ *                 in some instances and should be handled mostly the same. (Since 1.10)
  * @GST_EVENT_EOS: End-Of-Stream. No more data is to be expected to follow
  *                 without either a STREAM_START event, or a FLUSH_STOP and a SEGMENT
  *                 event.
@@ -151,6 +154,7 @@ typedef enum {
   GST_EVENT_TAG                   = GST_EVENT_MAKE_TYPE (80, FLAG(DOWNSTREAM) | FLAG(SERIALIZED) | FLAG(STICKY) | FLAG(STICKY_MULTI)),
   GST_EVENT_BUFFERSIZE            = GST_EVENT_MAKE_TYPE (90, FLAG(DOWNSTREAM) | FLAG(SERIALIZED) | FLAG(STICKY)),
   GST_EVENT_SINK_MESSAGE          = GST_EVENT_MAKE_TYPE (100, FLAG(DOWNSTREAM) | FLAG(SERIALIZED) | FLAG(STICKY) | FLAG(STICKY_MULTI)),
+  GST_EVENT_STREAM_GROUP_DONE     = GST_EVENT_MAKE_TYPE (105, FLAG(DOWNSTREAM) | FLAG(SERIALIZED) | FLAG(STICKY)),
   GST_EVENT_EOS                   = GST_EVENT_MAKE_TYPE (110, FLAG(DOWNSTREAM) | FLAG(SERIALIZED) | FLAG(STICKY)),
   GST_EVENT_TOC                   = GST_EVENT_MAKE_TYPE (120, FLAG(DOWNSTREAM) | FLAG(SERIALIZED) | FLAG(STICKY) | FLAG(STICKY_MULTI)),
   GST_EVENT_PROTECTION            = GST_EVENT_MAKE_TYPE (130, FLAG (DOWNSTREAM) | FLAG (SERIALIZED) | FLAG (STICKY) | FLAG (STICKY_MULTI)),
@@ -496,6 +500,10 @@ void            gst_event_parse_stream_collection (GstEvent *event, GstStreamCol
 GstEvent *      gst_event_new_select_streams    (GList *streams);
 void            gst_event_parse_select_streams  (GstEvent *event, GList **streams);
 
+/* stream-group-done event */
+GstEvent *      gst_event_new_stream_group_done (const guint group_id) G_GNUC_MALLOC;
+void            gst_event_parse_stream_group_done (GstEvent *event, guint *group_id);
+
 /* EOS event */
 GstEvent *      gst_event_new_eos               (void) G_GNUC_MALLOC;
 
diff --git a/gst/gstpad.c b/gst/gstpad.c
index 3f5afd6b06..cd9fff1926 100644
--- a/gst/gstpad.c
+++ b/gst/gstpad.c
@@ -5035,8 +5035,9 @@ store_sticky_event (GstPad * pad, GstEvent * event)
   /* Unset the EOS flag when received STREAM_START event, so pad can
    * store sticky event and then push it later */
   if (type == GST_EVENT_STREAM_START) {
-    GST_LOG_OBJECT (pad, "Removing pending EOS events");
+    GST_LOG_OBJECT (pad, "Removing pending EOS and StreamGroupDone events");
     remove_event_by_type (pad, GST_EVENT_EOS);
+    remove_event_by_type (pad, GST_EVENT_STREAM_GROUP_DONE);
     GST_OBJECT_FLAG_UNSET (pad, GST_PAD_FLAG_EOS);
   }
 
@@ -5202,6 +5203,7 @@ gst_pad_push_event_unchecked (GstPad * pad, GstEvent * event,
       /* Remove sticky EOS events */
       GST_LOG_OBJECT (pad, "Removing pending EOS events");
       remove_event_by_type (pad, GST_EVENT_EOS);
+      remove_event_by_type (pad, GST_EVENT_STREAM_GROUP_DONE);
       remove_event_by_type (pad, GST_EVENT_SEGMENT);
       GST_OBJECT_FLAG_UNSET (pad, GST_PAD_FLAG_EOS);
       pad->ABI.abi.last_flowret = GST_FLOW_OK;
@@ -5526,6 +5528,7 @@ gst_pad_send_event_unchecked (GstPad * pad, GstEvent * event,
       /* Remove pending EOS events */
       GST_LOG_OBJECT (pad, "Removing pending EOS and SEGMENT events");
       remove_event_by_type (pad, GST_EVENT_EOS);
+      remove_event_by_type (pad, GST_EVENT_STREAM_GROUP_DONE);
       remove_event_by_type (pad, GST_EVENT_SEGMENT);
       GST_OBJECT_FLAG_UNSET (pad, GST_PAD_FLAG_EOS);
       pad->ABI.abi.last_flowret = GST_FLOW_OK;
@@ -5553,6 +5556,7 @@ gst_pad_send_event_unchecked (GstPad * pad, GstEvent * event,
           /* Remove sticky EOS events */
           GST_LOG_OBJECT (pad, "Removing pending EOS events");
           remove_event_by_type (pad, GST_EVENT_EOS);
+          remove_event_by_type (pad, GST_EVENT_STREAM_GROUP_DONE);
           GST_OBJECT_FLAG_UNSET (pad, GST_PAD_FLAG_EOS);
           break;
         default:
diff --git a/gst/gstquark.c b/gst/gstquark.c
index c2a204db2b..4500cc63d6 100644
--- a/gst/gstquark.c
+++ b/gst/gstquark.c
@@ -74,7 +74,8 @@ static const gchar *_quark_strings[] = {
   "property-value", "streams", "GstEventSelectStreams",
   "GstMessageStreamCollection", "collection", "stream", "stream-collection",
   "GstMessageStreamsSelected", "GstMessageRedirect", "redirect-entry-locations",
-  "redirect-entry-taglists", "redirect-entry-structures"
+  "redirect-entry-taglists", "redirect-entry-structures",
+  "GstEventStreamGroupDone"
 };
 
 GQuark _priv_gst_quark_table[GST_QUARK_MAX];
diff --git a/gst/gstquark.h b/gst/gstquark.h
index fda5deb97e..e41466bae1 100644
--- a/gst/gstquark.h
+++ b/gst/gstquark.h
@@ -216,7 +216,8 @@ typedef enum _GstQuarkId
   GST_QUARK_REDIRECT_ENTRY_LOCATIONS = 185,
   GST_QUARK_REDIRECT_ENTRY_TAGLISTS = 186,
   GST_QUARK_REDIRECT_ENTRY_STRUCTURES = 187,
-  GST_QUARK_MAX = 188
+  GST_QUARK_EVENT_STREAM_GROUP_DONE = 188,
+  GST_QUARK_MAX = 189
 } GstQuarkId;
 
 extern GQuark _priv_gst_quark_table[GST_QUARK_MAX];