mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-30 12:10:37 +00:00
87 lines
4 KiB
Markdown
87 lines
4 KiB
Markdown
# 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
|
|
but 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 be
|
|
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.
|
|
|
|
## Scenarios
|
|
|
|
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 one. 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 its seqnum 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. These
|
|
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 one received first.
|
|
|
|
Also, when handling the seek, the element might push `FLUSH_START`,
|
|
`FLUSH_STOP` and a segment event. All these events should have the
|
|
seqnum of the received seek event. When this segment is over and an
|
|
`EOS/SEGMENT_DONE` event is going to be pushed, it should also have the
|
|
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.
|