From: Thiago Santos Date: Thu, 23 Jan 2014 18:34:27 +0000 (-0300) Subject: docs: design: add part-seqnums X-Git-Tag: 1.3.1~199 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=5880c9c4c38911bced21854383a5b836d2875f71;p=platform%2Fupstream%2Fgstreamer.git 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 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.