gstreamer/docs/design/part-seqnums.txt

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.