docs/design/part-probes.txt

   1 Probes
   2 ------
   3
   4  Probes are callbacks that can be installed by the application and will notify
   5  the application about the states of the dataflow.
   6
   7
   8 Requirements
   9 ------------
  10
  11 Applications should be able to monitor and control the dataflow on pads. We
  12 identify the following types:
  13
  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.
  17
  18  - be notified when data, events or queries are pushed or sent on a pad. It
  19    should also be possible to inspect and modify the data.
  20
  21  - be able to drop, pass and block on data based on the result of the callback.
  22
  23  - be able to drop, pass data on blocking pads based on methods performed by
  24    the application thread.
  25
  26
  27 Overview
  28 --------
  29
  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.
  32
  33    gulong  gst_pad_add_probe    (GstPad *pad,
  34                                  GstPadProbeType mask,
  35                                  GstPadProbeCallback callback,
  36                                  gpointer user_data,
  37                                  GDestroyNotify destroy_data);
  38
  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():
  41
  42    void    gst_pad_remove_probe (GstPad *pad, gulong id);
  43
  44  The mask parameter is a bitwise or of the following flags:
  45
  46     typedef enum
  47     {
  48       GST_PAD_PROBE_TYPE_INVALID          = 0,
  49
  50       /* flags to control blocking */
  51       GST_PAD_PROBE_TYPE_IDLE             = (1 << 0),
  52       GST_PAD_PROBE_TYPE_BLOCK            = (1 << 1),
  53
  54       /* flags to select datatypes */
  55       GST_PAD_PROBE_TYPE_BUFFER           = (1 << 4),
  56       GST_PAD_PROBE_TYPE_BUFFER_LIST      = (1 << 5),
  57       GST_PAD_PROBE_TYPE_EVENT_DOWNSTREAM = (1 << 6),
  58       GST_PAD_PROBE_TYPE_EVENT_UPSTREAM   = (1 << 7),
  59       GST_PAD_PROBE_TYPE_EVENT_FLUSH      = (1 << 8),
  60       GST_PAD_PROBE_TYPE_QUERY_DOWNSTREAM = (1 << 9),
  61       GST_PAD_PROBE_TYPE_QUERY_UPSTREAM   = (1 << 10),
  62
  63       /* flags to select scheduling mode */
  64       GST_PAD_PROBE_TYPE_PUSH             = (1 << 12),
  65       GST_PAD_PROBE_TYPE_PULL             = (1 << 13),
  66
  67     } GstPadProbeType;
  68
  69  When adding a probe with the IDLE or BLOCK flag, the probe will become a
  70  blocking probe (see below). Otherwise the probe will be a DATA probe.
  71
  72  The datatype and scheduling selector flags are used to select what kind of
  73  datatypes and scheduling modes should be allowed in the callback.
  74
  75  The blocking flags must match the triggered probe exactly.
  76
  77  The probe callback is defined as:
  78
  79    GstPadProbeReturn (*GstPadProbeCallback) (GstPad *pad, GstPadProbeInfo *info,
  80                                           gpointer user_data);
  81
  82  A probe info structure is passed as an argument and its type is guaranteed
  83  to match the mask that was used to register the callback. The data item in the
  84  info contains type specific data, which is usually the data item that is blocked
  85  or NULL when no data item is present.
  86
  87  The probe can return any of the following return values:
  88
  89    typedef enum
  90    {
  91      GST_PAD_PROBE_DROP,
  92      GST_PAD_PROBE_OK,
  93      GST_PAD_PROBE_REMOVE,
  94      GST_PAD_PROBE_PASS,
  95    } GstPadProbeReturn;
  96
  97  GST_PAD_PROBE_OK is the normal return value.  DROP will drop the item that is
  98  currently being probed. GST_PAD_PROBE_REMOVE the currently executing probe from the
  99  list of probes.
 100
 101  GST_PAD_PROBE_PASS is relevant for blocking probes and will temporarily unblock the
 102  pad and let the item trough, it will then block again on the next item.
 103
 104
 105 Blocking probes
 106 ---------------
 107
 108   Blocking probes are probes with BLOCK or IDLE flags set. They will always
 109   block the dataflow and trigger the callback according to the following rules:
 110
 111   When the IDLE flag is set, the probe callback is called as soon as no data is
 112   flowing over the pad. If at the time of probe registration, the pad is idle,
 113   the callback will be called immediately from the current thread. Otherwise,
 114   the callback will be called as soon as the pad becomes idle in the streaming
 115   thread.
 116
 117   The IDLE probe is useful to perform dynamic linking, it allows to wait for for
 118   a safe moment when an unlink/link operation can be done. Since the probe is a
 119   blocking probe, it will also make sure that the pad stays idle until the probe
 120   is removed.
 121
 122   When the BLOCK flag is set, the probe callback will be called when new data
 123   arrives on the pad and right before the pad goes into the blocking state. This
 124   callback is thus only called when there is new data on the pad.
 125
 126   The blocking probe is removed with gst_pad_remove_probe() or when the probe
 127   callback return GST_PAD_PROBE_REMOVE. In both cases, and if this was the last
 128   blocking probe on the pad, the pad is unblocked and dataflow can continue.
 129
 130
 131 Non-Blocking probes
 132 --------------------
 133
 134   Non-blocking probes or DATA probes are probes triggered when data is flowing
 135   over the pad. The are called after the blocking probes are run and always with
 136   data.
 137
 138
 139 Push dataflow
 140 -------------
 141
 142 Push probes have the GST_PAD_PROBE_TYPE_PUSH flag set in the callbacks.
 143
 144 In push based scheduling, the blocking probe is called first with the data item.
 145 Then the data probes are called before the peer pad chain or event function is
 146 called.
 147
 148 The data probes are called before the peer pad is checked. This allows for
 149 linking the pad in either the BLOCK or DATA probes on the pad.
 150
 151 Before the peerpad chain or event function is called, the peer pad block and
 152 data probes are called.
 153
 154 Finally, the IDLE probe is called on the pad after the data was sent to the
 155 peer pad.
 156
 157 The push dataflow probe behavior is the same for buffers and bidirectional events.
 158
 159
 160                      pad                           peerpad
 161                       |                               |
 162  gst_pad_push() /     |                               |
 163  gst_pad_push_event() |                               |
 164  -------------------->O                               |
 165                       O                               |
 166         flushing?     O                               |
 167         WRONG_STATE   O                               |
 168         < - - - - - - O                               |
 169                       O-> do BLOCK probes             |
 170                       O                               |
 171                       O-> do DATA probes              |
 172          no peer?     O                               |
 173         NOT_LINKED    O                               |
 174         < - - - - - - O                               |
 175                       O   gst_pad_chain() /           |
 176                       O   gst_pad_send_event()        |
 177                       O------------------------------>O
 178                       O                   flushing?   O
 179                       O                 WRONG_STATE   O
 180                       O< - - - - - - - - - - - - - - -O
 181                       O                               O-> do BLOCK probes
 182                       O                               O
 183                       O                               O-> do DATA probes
 184                       O                               O
 185                       O                               O---> chainfunc /
 186                       O                               O     eventfunc
 187                       O< - - - - - - - - - - - - - - -O
 188                       O                               |
 189                       O-> do IDLE probes              |
 190                       O                               |
 191         < - - - - - - O                               |
 192                       |                               |
 193
 194
 195 Pull dataflow
 196 -------------
 197
 198 Pull probes have the GST_PAD_PROBE_TYPE_PULL flag set in the callbacks.
 199
 200 The gst_pad_pull_range() call will first trigger the BLOCK probes without a DATA
 201 item. This allows the pad to be linked before the peer pad is resolved. It also
 202 allows the callback to set a data item in the probe info.
 203
 204 After the blocking probe and the getrange function is called on the peer pad
 205 and there is a data item, the DATA probes are called.
 206
 207 When control returns to the sinkpad, the IDLE callbacks are called. The IDLE
 208 callback is called without a data item so that it will also be called when there
 209 was an error.
 210
 211 If there is a valid DATA item, the DATA probes are called for the item.
 212
 213
 214                  srcpad                          sinkpad
 215                    |                               |
 216                    |                               | gst_pad_pull_range()
 217                    |                               O<---------------------
 218                    |                               O
 219                    |                               O  flushing?
 220                    |                               O  WRONG_STATE
 221                    |                               O - - - - - - - - - - >
 222                    |             do BLOCK probes <-O
 223                    |                               O   no peer?
 224                    |                               O  NOT_LINKED
 225                    |                               O - - - - - - - - - - >
 226                    |          gst_pad_get_range()  O
 227                    O<------------------------------O
 228                    O                               O
 229                    O flushing?                     O
 230                    O WRONG_STATE                   O
 231                    O- - - - - - - - - - - - - - - >O
 232  do BLOCK probes <-O                               O
 233                    O                               O
 234   getrangefunc <---O                               O
 235                    O  flow error?                  O
 236                    O- - - - - - - - - - - - - - - >O
 237                    O                               O
 238   do DATA probes <-O                               O
 239                    O- - - - - - - - - - - - - - - >O
 240                    |                               O
 241                    |              do IDLE probes <-O
 242                    |                               O   flow error?
 243                    |                               O - - - - - - - - - - >
 244                    |                               O
 245                    |              do DATA probes <-O
 246                    |                               O - - - - - - - - - - >
 247                    |                               |
 248
 249
 250 Queries
 251 -------
 252
 253 Query probes have the GST_PAD_PROBE_TYPE_QUERY_* flag set in the callbacks.
 254
 255
 256                      pad                           peerpad
 257                       |                               |
 258  gst_pad_peer_query() |                               |
 259  -------------------->O                               |
 260                       O                               |
 261                       O-> do BLOCK probes             |
 262                       O                               |
 263                       O-> do QUERY | PUSH probes      |
 264          no peer?     O                               |
 265            FALSE      O                               |
 266         < - - - - - - O                               |
 267                       O   gst_pad_query()             |
 268                       O------------------------------>O
 269                       O                               O-> do BLOCK probes
 270                       O                               O
 271                       O                               O-> do QUERY | PUSH probes
 272                       O                               O
 273                       O                               O---> queryfunc
 274                       O                    error      O
 275         <- - - - - - - - - - - - - - - - - - - - - - -O
 276                       O                               O
 277                       O                               O-> do QUERY | PULL probes
 278                       O< - - - - - - - - - - - - - - -O
 279                       O                               |
 280                       O-> do QUERY | PULL probes      |
 281                       O                               |
 282         < - - - - - - O                               |
 283                       |                               |
 284
 285 For queries, the PUSH ProbeType is set when the query is traveling to the object
 286 that will answer the query and the PULL type is set when the query contains the
 287 answer.