docs/design/part-seqnums.txt - mtk-gstreamer-debian - Git at Google

 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.
	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.