GitLab will be down for maintenance this Sunday 13th June, from approx 7-11am UTC. This is for a PostgreSQL migration. See the tracker issue for more informations.

Commit 7f350cad authored by Alba Mendez's avatar Alba Mendez
Browse files

events.md: introduce forwarding and internal links

see https://twitter.com/mild_sunrise/status/1354582757851197443 for a rationale
parent 26a2a215
Pipeline #262814 waiting for manual action with stages
in 18 seconds
......@@ -11,6 +11,33 @@ pipeline is not handling them correctly the whole event system of the
pipeline is broken. We will try to explain here how these methods work
and how elements are supposed to implement them.
## Event handling
To send an event to an element, `gst_pad_send_event` is called on one of their
pads. Downstream events are sent to sink pads, upstream events to source pads.
When that happens, the event handler of that pad is called. Often, the handler
must forward the event to the next element(s) by pushing it to the appropriate
pad(s): downstream events are pushed to the element's source pads, upstream
events to sink pads. When the event is pushed using `gst_pad_push_event`,
it's sent to the linked pad and the process starts again (at the next element).
The default event handler `gst_pad_event_default` will, depending on the
event, drop it or forward it. Forwarding is done using `gst_pad_forward`,
which obtains a list of internally linked pads and pushes the event to each
of them.
## Internally linked pads
Each pad is internally linked to other pads in the same element. Internal
links can be queried through the `gst_pad_iterate_internal_links`
method. By default, it just looks for all the pads of the opposite direction;
that is, a sink pad is internally linked to all of the source pads in the
element, and vice versa.
Internal links are used to forward queries and events; for complex N-to-N
elements it might be a good idea to override them as appropriate.
## Downstream events
Downstream events are received through the sink pad's event handler, as
......@@ -23,7 +50,7 @@ thread that is processing the buffers, skipping ahead of buffers being
processed or queued in the pipeline). The most common downstream events
(SEGMENT, CAPS, TAG, EOS) are all serialised with the buffer flow.
Here is a typical event function:
Here is a typical event handler function:
``` c
static gboolean
......@@ -89,14 +116,9 @@ generate an upstream seek event.
The most common upstream events are seek events, Quality-of-Service
(QoS) and reconfigure events.
An upstream event can be sent using the `gst_pad_send_event` function.
This function simply call the default event handler of that pad. The
default event handler of pads is `gst_pad_event_default`, and it
basically sends the event to the peer of the internally linked pad. So
upstream events always arrive on the src pad of your element and are
handled by the default event handler except if you override that handler
to handle it yourself. There are some specific cases where you have to
do that :
Upstream events always arrive on the src pad of your element and are
usually handled by the default event handler. There are some specific
cases where you may need to provide your own handler:
- If you have multiple sink pads in your element. In that case you
will have to decide which one of the sink pads you will send the
......@@ -106,14 +128,13 @@ do that :
event that you will want to convert before sending it upstream, or a
QoS event that you want to handle.
The processing you will do in that event handler does not really matter
but there are important rules you have to absolutely respect because one
broken element event handler is breaking the whole pipeline event
handling. Here they are :
The processing you do in that event handler does not really matter
but there are important rules you have to absolutely respect; one
broken element event handler breaks the whole pipeline event handling.
Here they are:
- Always handle events you won't handle using the default
`gst_pad_event_default` method. This method will depending on the
event, forward the event or drop it.
- Always pass events you won't handle to the default event handler,
the `gst_pad_event_default` method.
- If you are generating some new event based on the one you received
don't forget to gst\_event\_unref the event you received.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment