3 Probes are callbacks that can be installed by the application and will notify
4 the application about the states of the dataflow.
8 Applications should be able to monitor and control the dataflow on pads.
9 We identify the following types:
11 - be notified when the pad is/becomes idle and make sure the pad stays
12 idle. This is essential to be able to implement dynamic relinking of
13 elements without breaking the dataflow.
15 - be notified when data, events or queries are pushed or sent on a
16 pad. It should also be possible to inspect and modify the data.
18 - be able to drop, pass and block on data based on the result of the
21 - be able to drop, pass data on blocking pads based on methods
22 performed by the application
27 The function `gst_pad_add_probe()` is used to add a probe to a pad. It accepts a
28 probe type mask and a callback.
31 gulong gst_pad_add_probe (GstPad *pad,
33 GstPadProbeCallback callback,
35 GDestroyNotify destroy_data);
38 The function returns a gulong that uniquely identifies the probe and that can
39 be used to remove the probe with `gst_pad_remove_probe()`:
42 void gst_pad_remove_probe (GstPad *pad, gulong id);
45 The mask parameter is a bitwise or of the following flags:
50 GST_PAD_PROBE_TYPE_INVALID = 0,
52 /* flags to control blocking */
53 GST_PAD_PROBE_TYPE_IDLE = (1 << 0),
54 GST_PAD_PROBE_TYPE_BLOCK = (1 << 1),
56 /* flags to select datatypes */
57 GST_PAD_PROBE_TYPE_BUFFER = (1 << 4),
58 GST_PAD_PROBE_TYPE_BUFFER_LIST = (1 << 5),
59 GST_PAD_PROBE_TYPE_EVENT_DOWNSTREAM = (1 << 6),
60 GST_PAD_PROBE_TYPE_EVENT_UPSTREAM = (1 << 7),
61 GST_PAD_PROBE_TYPE_EVENT_FLUSH = (1 << 8),
62 GST_PAD_PROBE_TYPE_QUERY_DOWNSTREAM = (1 << 9),
63 GST_PAD_PROBE_TYPE_QUERY_UPSTREAM = (1 << 10),
65 /* flags to select scheduling mode */
66 GST_PAD_PROBE_TYPE_PUSH = (1 << 12),
67 GST_PAD_PROBE_TYPE_PULL = (1 << 13),
71 When adding a probe with the IDLE or BLOCK flag, the probe will become a
72 blocking probe (see below). Otherwise the probe will be a DATA probe.
74 The datatype and scheduling selector flags are used to select what kind of
75 datatypes and scheduling modes should be allowed in the callback.
77 The blocking flags must match the triggered probe exactly.
79 The probe callback is defined as:
82 GstPadProbeReturn (*GstPadProbeCallback) (GstPad *pad, GstPadProbeInfo *info,
86 A probe info structure is passed as an argument and its type is guaranteed
87 to match the mask that was used to register the callback. The data item in the
88 info contains type specific data, which is usually the data item that is blocked
89 or `NULL` when no data item is present.
91 The probe can return any of the following return values:
100 GST_PAD_PROBE_HANDLED
104 `GST_PAD_PROBE_OK` is the normal return value. `_DROP` will drop the item that is
105 currently being probed. `GST_PAD_PROBE_REMOVE`: remove the currently executing probe from the
108 `GST_PAD_PROBE_PASS` is relevant for blocking probes and will temporarily unblock the
109 pad and let the item trough, it will then block again on the next item.
113 Blocking probes are probes with `BLOCK` or `IDLE` flags set. They will always
114 block the dataflow and trigger the callback according to the following rules:
116 When the `IDLE` flag is set, the probe callback is called as soon as no data is
117 flowing over the pad. If at the time of probe registration, the pad is idle,
118 the callback will be called immediately from the current thread. Otherwise,
119 the callback will be called as soon as the pad becomes idle in the streaming
122 The `IDLE` probe is useful to perform dynamic linking, it allows to wait for for
123 a safe moment when an unlink/link operation can be done. Since the probe is a
124 blocking probe, it will also make sure that the pad stays idle until the probe
127 When the `BLOCK` flag is set, the probe callback will be called when new data
128 arrives on the pad and right before the pad goes into the blocking state. This
129 callback is thus only called when there is new data on the pad.
131 The blocking probe is removed with `gst_pad_remove_probe()` or when the probe
132 callback return `GST_PAD_PROBE_REMOVE`. In both cases, and if this was the last
133 blocking probe on the pad, the pad is unblocked and dataflow can continue.
135 ## Non-Blocking probes
137 Non-blocking probes or DATA probes are probes triggered when data is flowing
138 over the pad. The are called after the blocking probes are run and always with
143 Push probes have the `GST_PAD_PROBE_TYPE_PUSH` flag set in the
146 In push based scheduling, the blocking probe is called first with the
147 data item. Then the data probes are called before the peer pad chain or
148 event function is called.
150 The data probes are called before the peer pad is checked. This allows
151 for linking the pad in either the BLOCK or DATA probes on the pad.
153 Before the peerpad chain or event function is called, the peer pad block
154 and data probes are called.
156 Finally, the `IDLE` probe is called on the pad after the data was sent to
159 The push dataflow probe behavior is the same for buffers and
160 bidirectional events.
166 gst_pad_push_event() | |
167 -------------------->O |
172 O-> do BLOCK probes |
178 O gst_pad_chain() / |
179 O gst_pad_send_event() |
180 O------------------------------>O
183 O< - - - - - - - - - - - - - - -O
184 O O-> do BLOCK probes
190 O< - - - - - - - - - - - - - - -O
200 Pull probes have the `GST_PAD_PROBE_TYPE_PULL` flag set in the
203 The `gst_pad_pull_range()` call will first trigger the `BLOCK` probes
204 without a `DATA` item. This allows the pad to be linked before the peer
205 pad is resolved. It also allows the callback to set a data item in the
208 After the blocking probe and the getrange function is called on the peer
209 pad and there is a data item, the DATA probes are called.
211 When control returns to the sinkpad, the `IDLE` callbacks are called. The
212 `IDLE` callback is called without a data item so that it will also be
213 called when there was an error.
215 If there is a valid `DATA` item, the `DATA` probes are called for the item.
220 | | gst_pad_pull_range()
221 | O<---------------------
225 | O - - - - - - - - - - >
226 | do BLOCK probes <-O
229 | O - - - - - - - - - - >
230 | gst_pad_get_range() O
231 O<------------------------------O
235 O- - - - - - - - - - - - - - - >O
236 do BLOCK probes <-O O
240 O- - - - - - - - - - - - - - - >O
243 O- - - - - - - - - - - - - - - >O
247 | O - - - - - - - - - - >
250 | O - - - - - - - - - - >
256 Query probes have the `GST_PAD_PROBE_TYPE_QUERY_*` flag set in the
262 gst_pad_peer_query() | |
263 -------------------->O |
265 O-> do BLOCK probes |
267 O-> do QUERY | PUSH probes |
272 O------------------------------>O
273 O O-> do BLOCK probes
275 O O-> do QUERY | PUSH probes
279 <- - - - - - - - - - - - - - - - - - - - - - -O
281 O O-> do QUERY | PULL probes
282 O< - - - - - - - - - - - - - - -O
284 O-> do QUERY | PULL probes |
290 For queries, the `PUSH` `ProbeType` is set when the query is traveling to
291 the object that will answer the query and the `PULL` type is set when the
292 query contains the answer.
296 ### Prerolling a partial pipeline
299 .---------. .---------. .----------.
300 | filesrc | | demuxer | .-----. | decoder1 |
301 | src -> sink src1 ->|queue|-> sink src
302 '---------' | | '-----' '----------' X
304 | | .-----. | decoder2 |
305 | src2 ->|queue|-> sink src
306 '---------' '-----' '----------' X
309 The purpose is to create the pipeline dynamically up to the decoders but
310 not yet connect them to a sink and without losing any data.
312 To do this, the source pads of the decoders is blocked so that no events
313 or buffers can escape and we don’t interrupt the stream.
315 When all of the dynamic pad are created (no-more-pads emitted by the
316 branching point, ie, the demuxer or the queues filled) and the pads are
317 blocked (blocked callback received) the pipeline is completely
320 It should then be possible to perform the following actions on the
323 - query duration/position
325 - perform a flushing seek to preroll a new position
327 - connect other elements and unblock the blocked pads.
329 ### dynamically switching an element in a PLAYING pipeline
332 .----------. .----------. .----------.
333 | element1 | | element2 | | element3 |
334 ... src -> sink src -> sink ...
335 '----------' '----------' '----------'
342 The purpose is to replace element2 with element4 in the `PLAYING`
345 1) block element1 src pad.
346 2) inside the block callback nothing is flowing between
347 element1 and element2 and nothing will flow until unblocked.
348 3) unlink element1 and element2
349 4) optional step: make sure data is flushed out of element2:
350 4a) pad event probe on element2 src
351 4b) send `EOS` to element2, this makes sure that element2 flushes out the last bits of data it holds.
352 4c) wait for `EOS` to appear in the probe, drop the `EOS`.
353 4d) remove the `EOS` pad event probe.
354 5) unlink element2 and element3
355 5a) optionally element2 can now be set to `NULL` and/or removed from the pipeline.
356 6) link element4 and element3
357 7) link element1 and element4
358 8) make sure element4 is in the same state as the rest of the elements. The
359 element should at least be `PAUSED`.
360 9) unblock element1 src
362 The same flow can be used to replace an element in a `PAUSED` pipeline. Of
363 course in a `PAUSED` pipeline there might not be dataflow so the block
364 might not immediately happen.