mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-02 14:36:41 +00:00
5880c9c4c3
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
91 lines
4 KiB
Text
91 lines
4 KiB
Text
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.
|