4 Probes are callbacks that can be installed by the application and will notify
5 the application about the states of the dataflow.
11 Applications should be able to monitor and control the dataflow on pads. We
12 identify the following types:
14 - be notified when the pad is/becomes idle and make sure the pad stays idle.
15 This is essential to be able to implement dynamic relinking of elements
16 without breaking the dataflow.
18 - be notified when data or events are pushed or sent on a pad. It should also
19 be possible to inspect and modify the data.
21 - be able to drop, pass and block on data based on the result of the callback.
23 - be able to drop, pass data on blocking pads based on methods performed by
24 the application thread.
30 The function gst_pad_add_probe() is used to add a probe to a pad. It accepts a
31 probe type mask and a callback.
33 gulong gst_pad_add_probe (GstPad *pad,
35 GstPadProbeCallback callback,
37 GDestroyNotify destroy_data);
39 The function returns a gulong that uniquely identifies the probe and that can
40 be used to remove the probe with gst_pad_remove_probe():
42 void gst_pad_remove_probe (GstPad *pad, gulong id);
44 The mask parameter is a bitwise or of the following flags:
48 GST_PAD_PROBE_TYPE_INVALID = 0,
50 /* flags to control blocking */
51 GST_PAD_PROBE_TYPE_IDLE = (1 << 0),
52 GST_PAD_PROBE_TYPE_BLOCK = (1 << 1),
54 /* flags to select datatypes */
55 GST_PAD_PROBE_TYPE_BUFFER = (1 << 2),
56 GST_PAD_PROBE_TYPE_BUFFER_LIST = (1 << 3),
57 GST_PAD_PROBE_TYPE_EVENT_DOWNSTREAM = (1 << 4),
58 GST_PAD_PROBE_TYPE_EVENT_UPSTREAM = (1 << 5),
60 /* flags to select scheduling mode */
61 GST_PAD_PROBE_TYPE_PUSH = (1 << 6),
62 GST_PAD_PROBE_TYPE_PULL = (1 << 7),
66 When adding a probe with the IDLE or BLOCK flag, the probe will become a
67 blocking probe (see below). Otherwise the probe will be a DATA probe.
69 The datatype and scheduling selector flags are used to select what kind of
70 datatypes and scheduling modes should be allowed in the callback.
72 The blocking flags must match the triggered probe exactly.
74 The probe callback is defined as:
76 GstPadProbeReturn (*GstPadProbeCallback) (GstPad *pad, GstPadProbeInfo *info,
79 A probe info structure is passed as an argument and its type is guaranteed
80 to match the mask that was used to register the callback. The data item in the
81 info contains type specific data, which is usually the data item that is blocked
82 or NULL when no data item is present.
84 The probe can return any of the following return values:
94 GST_PAD_PROBE_OK is the normal return value. DROP will drop the item that is
95 currently being probed. GST_PAD_PROBE_REMOVE the currently executing probe from the
98 GST_PAD_PROBE_PASS is relevant for blocking probes and will temporarily unblock the
99 pad and let the item trough, it will then block again on the next item.
105 Blocking probes are probes with BLOCK or IDLE flags set. They will always
106 block the dataflow and trigger the callback according to the following rules:
108 When the IDLE flag is set, the probe callback is called as soon as no data is
109 flowing over the pad. If at the time of probe registration, the pad is idle,
110 the callback will be called immediately from the current thread. Otherwise,
111 the callback will be called as soon as the pad becomes idle in the streaming
114 The IDLE probe in useful to perform dynamic linking, it allows to wait for for
115 a safe moment when an unlink/link operation can be done. Since the probe is a
116 blocking probe, it will also make sure that the pad stays idle until the probe
119 When the BLOCK flag is set, the probe callback will be called when new data
120 arrives on the pad and right before the pad goes into the blocking state. This
121 callback is thus only called when there is new data on the pad.
123 The blocking probe is removed with gst_pad_remove_probe() or when the probe
124 callback return GST_PAD_PROBE_REMOVE. In both cases, and if this was the last
125 blocking probe on the pad, the pad is unblocked and dataflow can continue.
131 Non-blocking probes or DATA probes are probes triggered when data is flowing
132 over the pad. The are called after the blocking probes are run and always with
139 Push probes have the GST_PAD_PROBE_TYPE_PUSH flag set in the callbacks.
141 In push based scheduling, the blocking probe is called first with the data item.
142 Then the data probes are called before the peer pad chain or event function is
145 The data probes are called before the peer pad is checked. This allows for
146 linking the pad in either the BLOCK or DATA probes on the pad.
148 Before the peerpad chain or event function is called, the peer pad block and
149 data probes are called.
151 Finally, the IDLE probe is called on the pad after the data was sent to the
154 The push dataflow probe behavior is the same for buffers and bidirectional events.
160 gst_pad_push_event() | |
161 -------------------->O |
166 O-> do BLOCK probes |
172 O gst_pad_chain() / |
173 O gst_pad_send_event() |
174 O------------------------------>O
177 O< - - - - - - - - - - - - - - -O
178 O O-> do BLOCK probes
184 O< - - - - - - - - - - - - - - -O
195 Pull probes have the GST_PAD_PROBE_TYPE_PULL flag set in the callbacks.
197 The gst_pad_pull_range() call will first trigger the BLOCK probes without a DATA
198 item. This allows the pad to be linked before the peer pad is resolved. It also
199 allows the callback to set a data item in the probe info.
201 After the blocking probe and the getrange function is called on the peer pad
202 and there is a data item, the DATA probes are called.
204 When control returns to the sinkpad, the IDLE callbacks are called. The IDLE
205 callback is called without a data item so that it will also be called when there
208 If there is a valid DATA item, the DATA probes are called for the item.
213 | | gst_pad_pull_range()
214 | O<---------------------
218 | O - - - - - - - - - - >
219 | do BLOCK probes <-O
222 | O - - - - - - - - - - >
223 | gst_pad_get_range() O
224 O<------------------------------O
228 O- - - - - - - - - - - - - - - >O
229 do BLOCK probes <-O O
233 O- - - - - - - - - - - - - - - >O
236 O- - - - - - - - - - - - - - - >O
240 | O - - - - - - - - - - >
243 | O - - - - - - - - - - >
250 Query probes have the GST_PAD_PROBE_TYPE_QUERY_* flag set in the callbacks.
255 gst_pad_peer_query() | |
256 -------------------->O |
258 O-> do BLOCK probes |
260 O-> do QUERY | PUSH probes |
265 O------------------------------>O
266 O O-> do BLOCK probes
268 O O-> do QUERY | PUSH probes
272 <- - - - - - - - - - - - - - - - - - - - - - -O
274 O O-> do QUERY | PULL probes
275 O< - - - - - - - - - - - - - - -O
277 O-> do QUERY | PULL probes |