markdown/additional/design/probes.md

   1 # Probes
   2
   3 Probes are callbacks that can be installed by the application and will notify
   4 the application about the states of the dataflow.
   5
   6 ## Requirements
   7
   8 Applications should be able to monitor and control the dataflow on pads.
   9 We identify the following types:
  10
  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.
  14
  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.
  17
  18   - be able to drop, pass and block on data based on the result of the
  19     callback.
  20
  21   - be able to drop, pass data on blocking pads based on methods
  22     performed by the application
  23     thread.
  24
  25 ## Overview
  26
  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.
  29
  30 ``` c
  31     gulong  gst_pad_add_probe    (GstPad *pad,
  32                                   GstPadProbeType mask,
  33                                   GstPadProbeCallback callback,
  34                                   gpointer user_data,
  35                                   GDestroyNotify destroy_data);
  36 ```
  37
  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()`:
  40
  41 ``` c
  42     void    gst_pad_remove_probe (GstPad *pad, gulong id);
  43 ```
  44
  45 The mask parameter is a bitwise or of the following flags:
  46
  47 ``` c
  48 typedef enum
  49 {
  50   GST_PAD_PROBE_TYPE_INVALID          = 0,
  51
  52   /* flags to control blocking */
  53   GST_PAD_PROBE_TYPE_IDLE             = (1 << 0),
  54   GST_PAD_PROBE_TYPE_BLOCK            = (1 << 1),
  55
  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),
  64
  65   /* flags to select scheduling mode */
  66   GST_PAD_PROBE_TYPE_PUSH             = (1 << 12),
  67   GST_PAD_PROBE_TYPE_PULL             = (1 << 13),
  68 } GstPadProbeType;
  69 ```
  70
  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.
  73
  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.
  76
  77 The blocking flags must match the triggered probe exactly.
  78
  79 The probe callback is defined as:
  80
  81 ``` c
  82 GstPadProbeReturn (*GstPadProbeCallback) (GstPad *pad, GstPadProbeInfo *info,
  83     gpointer user_data);
  84 ```
  85
  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.
  90
  91 The probe can return any of the following return values:
  92
  93 ``` c
  94 typedef enum
  95 {
  96   GST_PAD_PROBE_DROP,
  97   GST_PAD_PROBE_OK,
  98   GST_PAD_PROBE_REMOVE,
  99   GST_PAD_PROBE_PASS,
 100   GST_PAD_PROBE_HANDLED
 101 } GstPadProbeReturn;
 102 ```
 103
 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
 106 list of probes.
 107
 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.
 110
 111 ## Blocking probes
 112
 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:
 115
 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
 120 thread.
 121
 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
 125 is removed.
 126
 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.
 130
 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.
 134
 135 ## Non-Blocking probes
 136
 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
 139 data.
 140
 141 ## Push dataflow
 142
 143 Push probes have the `GST_PAD_PROBE_TYPE_PUSH` flag set in the
 144 callbacks.
 145
 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.
 149
 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.
 152
 153 Before the peerpad chain or event function is called, the peer pad block
 154 and data probes are called.
 155
 156 Finally, the `IDLE` probe is called on the pad after the data was sent to
 157 the peer pad.
 158
 159 The push dataflow probe behavior is the same for buffers and
 160 bidirectional events.
 161
 162 ```
 163                     pad                           peerpad
 164                      |                               |
 165 gst_pad_push() /     |                               |
 166 gst_pad_push_event() |                               |
 167 -------------------->O                               |
 168                      O                               |
 169        flushing?     O                               |
 170        FLUSHING      O                               |
 171        < - - - - - - O                               |
 172                      O-> do BLOCK probes             |
 173                      O                               |
 174                      O-> do DATA probes              |
 175         no peer?     O                               |
 176        NOT_LINKED    O                               |
 177        < - - - - - - O                               |
 178                      O   gst_pad_chain() /           |
 179                      O   gst_pad_send_event()        |
 180                      O------------------------------>O
 181                      O                   flushing?   O
 182                      O                   FLUSHING    O
 183                      O< - - - - - - - - - - - - - - -O
 184                      O                               O-> do BLOCK probes
 185                      O                               O
 186                      O                               O-> do DATA probes
 187                      O                               O
 188                      O                               O---> chainfunc /
 189                      O                               O     eventfunc
 190                      O< - - - - - - - - - - - - - - -O
 191                      O                               |
 192                      O-> do IDLE probes              |
 193                      O                               |
 194        < - - - - - - O                               |
 195                      |                               |
 196 ```
 197
 198 ## Pull dataflow
 199
 200 Pull probes have the `GST_PAD_PROBE_TYPE_PULL` flag set in the
 201 callbacks.
 202
 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
 206 probe info.
 207
 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.
 210
 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.
 214
 215 If there is a valid `DATA` item, the `DATA` probes are called for the item.
 216
 217 ```
 218                 srcpad                          sinkpad
 219                   |                               |
 220                   |                               | gst_pad_pull_range()
 221                   |                               O<---------------------
 222                   |                               O
 223                   |                               O  flushing?
 224                   |                               O  FLUSHING
 225                   |                               O - - - - - - - - - - >
 226                   |             do BLOCK probes <-O
 227                   |                               O   no peer?
 228                   |                               O  NOT_LINKED
 229                   |                               O - - - - - - - - - - >
 230                   |          gst_pad_get_range()  O
 231                   O<------------------------------O
 232                   O                               O
 233                   O flushing?                     O
 234                   O FLUSHING                      O
 235                   O- - - - - - - - - - - - - - - >O
 236 do BLOCK probes <-O                               O
 237                   O                               O
 238  getrangefunc <---O                               O
 239                   O  flow error?                  O
 240                   O- - - - - - - - - - - - - - - >O
 241                   O                               O
 242  do DATA probes <-O                               O
 243                   O- - - - - - - - - - - - - - - >O
 244                   |                               O
 245                   |              do IDLE probes <-O
 246                   |                               O   flow error?
 247                   |                               O - - - - - - - - - - >
 248                   |                               O
 249                   |              do DATA probes <-O
 250                   |                               O - - - - - - - - - - >
 251                   |                               |
 252 ```
 253
 254 ## Queries
 255
 256 Query probes have the `GST_PAD_PROBE_TYPE_QUERY_*` flag set in the
 257 callbacks.
 258
 259 ```
 260                     pad                           peerpad
 261                      |                               |
 262 gst_pad_peer_query() |                               |
 263 -------------------->O                               |
 264                      O                               |
 265                      O-> do BLOCK probes             |
 266                      O                               |
 267                      O-> do QUERY | PUSH probes      |
 268         no peer?     O                               |
 269           FALSE      O                               |
 270        < - - - - - - O                               |
 271                      O   gst_pad_query()             |
 272                      O------------------------------>O
 273                      O                               O-> do BLOCK probes
 274                      O                               O
 275                      O                               O-> do QUERY | PUSH probes
 276                      O                               O
 277                      O                               O---> queryfunc
 278                      O                    error      O
 279        <- - - - - - - - - - - - - - - - - - - - - - -O
 280                      O                               O
 281                      O                               O-> do QUERY | PULL probes
 282                      O< - - - - - - - - - - - - - - -O
 283                      O                               |
 284                      O-> do QUERY | PULL probes      |
 285                      O                               |
 286        < - - - - - - O                               |
 287                      |                               |
 288 ```
 289
 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.
 293
 294 ## Use-cases
 295
 296 ### Prerolling a partial pipeline
 297
 298 ```
 299     .---------.      .---------.                .----------.
 300     | filesrc |      | demuxer |     .-----.    | decoder1 |
 301     |        src -> sink      src1 ->|queue|-> sink       src
 302     '---------'      |         |     '-----'    '----------' X
 303                      |         |                .----------.
 304                      |         |     .-----.    | decoder2 |
 305                      |        src2 ->|queue|-> sink       src
 306                      '---------'     '-----'    '----------' X
 307 ```
 308
 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.
 311
 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.
 314
 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
 318 prerolled.
 319
 320 It should then be possible to perform the following actions on the
 321 prerolled pipeline:
 322
 323   - query duration/position
 324
 325   - perform a flushing seek to preroll a new position
 326
 327   - connect other elements and unblock the blocked pads.
 328
 329 ### dynamically switching an element in a PLAYING pipeline
 330
 331 ```
 332  .----------.      .----------.      .----------.
 333  | element1 |      | element2 |      | element3 |
 334 ...        src -> sink       src -> sink       ...
 335  '----------'      '----------'      '----------'
 336                    .----------.
 337                    | element4 |
 338                   sink       src
 339                    '----------'
 340 ```
 341
 342 The purpose is to replace element2 with element4 in the `PLAYING`
 343 pipeline.
 344
 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
 361
 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.