The scheduling mode of a pad defines how data is retrieved from (source) or given to (sink) pads. GStreamer can operate in two scheduling mode, called push- and pull-mode. GStreamer supports elements with pads in any of the scheduling modes where not all pads need to be operating in the same mode.
So far, we have only discussed _chain ()
-operating
elements, i.e. elements that have a chain-function set on their sink pad
and push buffers on their source pad(s). We call this the push-mode
because a peer element will use gst_pad_push ()
on
a srcpad, which will cause our _chain ()
-function
to be called, which in turn causes our element to push out a buffer on
the source pad. The initiative to start the dataflow happens somewhere
upstream when it pushes out a buffer and all downstream elements get
scheduled when their _chain ()
-functions are
called in turn.
Before we explain pull-mode scheduling, let's first understand how the different scheduling modes are selected and activated on a pad.
During the element state change of READY->PAUSED, the pads of an
element will be activated. This happens first on the source pads and
then on the sink pads of the element. GStreamer calls the
_activate ()
of a pad. By default this function
will activate the pad in push-mode by calling
gst_pad_activate_mode ()
with the GST_PAD_MODE_PUSH
scheduling mode.
It is possible to override the _activate ()
of a pad
and decide on a different scheduling mode. You can know in what
scheduling mode a pad is activated by overriding the
_activate_mode ()
-function.
GStreamer allows the different pads of an element to operate in different scheduling modes. This allows for many different possible use-cases. What follows is an overview of some typical use-cases.
If all pads of an element are activated in push-mode scheduling,
the element as a whole is operating in push-mode.
For source elements this means that they will have to start a
task that pushes out buffers on the source pad to the downstream
elements.
Downstream elements will have data pushed to them by upstream elements
using the sinkpads _chain ()
-function which will
push out buffers on the source pads.
Prerequisites for this scheduling mode are that a chain-function was
set for each sinkpad using gst_pad_set_chain_function ()
and that all downstream elements operate in the same mode.
Alternatively, sinkpads can be the driving force behind a pipeline
by operating in pull-mode, while the sourcepads
of the element still operate in push-mode. In order to be the
driving force, those pads start a GstTask
when they are activated. This task is a thread, which
will call a function specified by the element. When called, this
function will have random data access (through
gst_pad_pull_range ()
) over all sinkpads, and
can push data over the sourcepads, which effectively means that
this element controls data flow in the pipeline. Prerequisites for
this mode are that all downstream elements can act in push
mode, and that all upstream elements operate in pull-mode (see below).
Source pads can be activated in PULL mode by a downstream element
when they return GST_PAD_MODE_PULL from the GST_QUERY_SCHEDULING
query. Prerequisites for this scheduling mode are that a
getrange-function was set for the source pad using
gst_pad_set_getrange_function ()
.
Lastly, all pads in an element can be activated in PULL-mode.
However, contrary to the above, this does not mean that they
start a task on their own. Rather, it means that they are pull
slave for the downstream element, and have to provide random data
access to it from their _get_range ()
-function.
Requirements are that the a _get_range
()
-function was set on this pad using the function
gst_pad_set_getrange_function ()
. Also, if
the element has any sinkpads, all those pads (and thereby their
peers) need to operate in PULL access mode, too.
When a sink element is activated in PULL mode, it should start a
task that calls gst_pad_pull_range ()
on its
sinkpad. It can only do this when the upstream SCHEDULING query
returns support for the GST_PAD_MODE_PULL scheduling mode.
In the next two sections, we will go closer into pull-mode scheduling (elements/pads driving the pipeline, and elements/pads providing random access), and some specific use cases will be given.