docs: design: add part-seqnums

Hopefully clarifies how seqnums should be used and copied from
events to events/messages when those are handled.

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

diff --git a/docs/design/part-seqnums.txt b/docs/design/part-seqnums.txt
new file mode 100644 (file)
index 0000000..1b6847d
--- /dev/null
+++ b/docs/design/part-seqnums.txt
@@ -0,0 +1,91 @@
+Seqnums (Sequence numbers)
+--------------------------
+
+Seqnums are integers associated to events and messages. They are used to
+identify a group of events and messages as being part of the same 'operation'
+over the pipeline.
+
+Whenever a new event or message is created, a seqnum is set into them. This
+seqnum is created from an ever increasing source (starting from 0 and it
+might wrap around), so each new event and message gets a new and hopefully
+unique seqnum.
+
+Suppose an element receives an event A and, as part of the logic of handling
+the event A, creates a new event B. B should have its seqnum to the same as A,
+because they are part of the same operation. The same logic applies if this
+element had to create multiple events or messages, all of those should have
+the seqnum set to the value on the received event. For example, when a sink
+element receives an EOS event and creates a new EOS message to post, it
+should copy the seqnum from the event to the message because the EOS message
+is a consequence of the EOS event being received.
+
+Preserving the seqnums accross related events and messages allows the elements
+and applications to identify a set of events/messages as being part of a single
+operation on the pipeline. For example, flushes, segments and EOS that are
+related to a seek event started by the application.
+
+Seqnums are also useful for elements to discard duplicated events, avoiding
+handling them again.
+
+Below are some scenarios as examples of how to handle seqnums when receving
+events:
+
+
+Forcing EOS on the pipeline
+---------------------------
+
+The application has a pipeline running and does a gst_element_send_event
+to the pipeline with an EOS event. All the sources in the pipeline will
+have their send_event handlers called and will receive the event from
+the application.
+
+When handling this event, the sources will push either the same EOS downstream
+or create their own EOS event and push. In the later case, the source should
+copy the seqnum from the original EOS to the newly created. This same logic
+applies to all elements that receive the EOS downstream, either push the
+same event or, if creating a new one, copy the seqnum.
+
+When the EOS reaches the sink, it will create an EOS message, copy the
+seqnum to the message and post to the bus. The application receives the
+message and can compare the seqnum of the message with the one from the
+original event sent to the pipeline. If they match, it knows that this
+EOS message was caused by the event it pushed and not from other reason
+(input finished or configured segment was over). 
+
+
+
+Seeking
+-------
+
+A seek event sent to the pipeline is forwarded to all sinks in it. Those
+sinks, then, push the seek event upstream until they reach an element
+that is capable of handling it. If the element handling the seek has
+multiple source pads (tipically a demuxer is handling the seek) it might
+receive the same seek event on all pads. To prevent handling the same
+seek event multiple times, the seqnum can be used to identify those
+events as being the same and only handle the first received.
+
+Also, when handling the seek, the element might push flush-start, flush-stop
+and a segment event. All those events should have the same seqnum of the seek
+event received. When this segment is over and an EOS/Segment-done event is
+going to be pushed, it also should have the same seqnum of the seek that
+originated the segment to be played.
+
+Having the same seqnum as the seek on the segment-done or EOS events is
+important for the application to identify that the segment requested
+by its seek has finished playing.
+
+
+
+Questions
+---------
+
+A) What happens if the application has sent a seek to the pipeline and,
+   while the segment relative to this seek is playing, it sends an EOS
+   event? Should the EOS pushed by the source have the seqnum of the
+   segment or the EOS from the application?
+
+If the EOS was received from the application before the segment ended, it
+should have the EOS from the application event. If the segment ends before
+the application event is received/handled, it should have the seek/segment
+seqnum.