gstreamer/markdown/design/seqnums.md

# 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

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.