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 or events are pushed or sent on a pad. It should also
  19    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                                  GstProbeType 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_PROBE_TYPE_INVALID      = 0,
  49
  50       /* flags to control blocking */
  51       GST_PROBE_TYPE_IDLE         = (1 << 0),
  52       GST_PROBE_TYPE_BLOCK        = (1 << 1),
  53
  54       /* flags to select datatypes */
  55       GST_PROBE_TYPE_BUFFER       = (1 << 2),
  56       GST_PROBE_TYPE_BUFFER_LIST  = (1 << 3),
  57       GST_PROBE_TYPE_EVENT        = (1 << 4),
  58
  59       /* flags to select scheduling mode */
  60       GST_PROBE_TYPE_PUSH         = (1 << 5),
  61       GST_PROBE_TYPE_PULL         = (1 << 6),
  62     } GstProbeType;
  63
  64  When adding a probe with the IDLE or BLOCK flag, the probe will become a
  65  blocking probe (see below). Otherwise the probe will be a DATA probe.
  66
  67  The datatype and scheduling selector flags are used to select what kind of
  68  datatypes and scheduling modes should be allowed in the callback.
  69
  70  The blocking flags must match the triggered probe exactly.
  71
  72  The probe callback is defined as:
  73
  74    GstProbeReturn (*GstPadProbeCallback) (GstPad *pad, GstProbeType type,
  75                                           gpointer type_data,
  76                                           gpointer user_data);
  77
  78  The executing probe type is passed as an argument and is guaranteed to match
  79  the mask that was used to register the callback. type_data contains type
  80  specific data, which is usually the data item that is blocked or NULL when
  81  no data item is present.
  82
  83  The probe can return any of the following return values:
  84
  85    typedef enum
  86    {
  87      GST_PROBE_DROP,
  88      GST_PROBE_OK,
  89      GST_PROBE_REMOVE,
  90      GST_PROBE_PASS,
  91    } GstProbeReturn;
  92
  93  GST_PROBE_OK is the normal return value.  DROP will drop the item that is
  94  currently being probed. GST_PROBE_REMOVE the currently executing probe from the
  95  list of probes.
  96
  97  GST_PROBE_PASS is relevant for blocking probes and will temporarily unblock the
  98  pad and let the item trough, it will then block again on the next item.
  99
 100
 101 Blocking probes
 102 ---------------
 103
 104   Blocking probes are probes with BLOCK or IDLE flags set. They will always
 105   block the dataflow and trigger the callback according to the following rules:
 106
 107   When the IDLE flag is set, the probe callback is called as soon as no data is
 108   flowing over the pad. If at the time of probe registration, the pad is idle,
 109   the callback will be called immediately from the current thread. Otherwise,
 110   the callback will be called as soon as the pad becomes idle in the streaming
 111   thread.
 112
 113   The IDLE probe in useful to perform dynamic linking, it allows to wait for for
 114   a safe moment when an unlink/link operation can be done. Since the event is a
 115   blocking event, it will also make sure that the pad stays idle until the probe
 116   is removed.
 117
 118   When the BLOCK flag is set, the probe callback will be called when new data
 119   arrives on the pad and right before the pad goes into the blocking state. This
 120   callback is thus only called when there is new data on the pad.
 121
 122   The blocking probe is removed with gst_pad_remove_probe() or when the probe
 123   callback return GST_PROBE_REMOVE. In both cases, and if this was the last
 124   blocking probe on the pad, the pad is unblocked and dataflow can continue.
 125
 126
 127 Non-Blocking probes
 128 --------------------
 129
 130   Non-blocking probes or DATA probes are probes triggered when data is flowing
 131   over the pad. The are called after the blocking probes are run and always with
 132   data.
 133
 134
 135 Push dataflow
 136 -------------
 137
 138 All probes have the GST_PROBE_TYPE_PUSH flag set in the callbacks.
 139
 140 In push based scheduling, the blocking probe is called first with the DATA item.
 141 Then the data probes are called before the peer pad chain function is called.
 142
 143 The data probes are called before the peer pad is checked. This allows for
 144 linking the pad in either the BLOCK or DATA probes on the srcpad.
 145
 146 Before the sinkpad chain function is called, the data probes are called.
 147
 148 Finally, the IDLE probe is called on the srcpad after the data was sent to the
 149 peer pad.
 150
 151
 152               srcpad                          sinkpad
 153                 |                               |
 154  gst_pad_push() |                               |
 155  -------------->O                               |
 156                 O                               |
 157   flushing?     O                               |
 158   WRONG_STATE   O                               |
 159   < - - - - - - O                               |
 160                 O-> do BLOCK probes             |
 161                 O                               |
 162                 O-> do DATA probes              |
 163    no peer?     O                               |
 164   NOT_LINKED    O                               |
 165   < - - - - - - O                               |
 166                 O   gst_pad_chain()             |
 167                 O------------------------------>O
 168                 O                   flushing?   O
 169                 O                 WRONG_STATE   O
 170                 O< - - - - - - - - - - - - - - -O
 171                 O                               O-> do DATA probes
 172                 O                               O
 173                 O                               O---> chainfunc
 174                 O< - - - - - - - - - - - - - - -O
 175                 O                               |
 176                 O-> do IDLE probes              |
 177                 O                               |
 178   < - - - - - - O                               |
 179                 |                               |
 180
 181
 182 Pull dataflow
 183 -------------
 184
 185 All probes have the GST_PROBE_TYPE_PULL flag set in the callbacks.
 186
 187 The gst_pad_pull_range() call will first trigger the BLOCK probes without a DATA
 188 item. This allows the pad to be linked before the peer pad is resolved.
 189
 190 After the getrange function is called on the peer pad and there is a data item,
 191 the DATA probes are called.
 192
 193 When control returns to the sinkpad, the IDLE callbacks are called.
 194
 195 It there is a valid DATA item, the DATA probes are called for the item.
 196
 197
 198                 srcpad                          sinkpad
 199                   |                               |
 200                   |                               | gst_pad_pull_range()
 201                   |                               O<---------------------
 202                   |                               O
 203                   |                               O  flushing?
 204                   |                               O  WRONG_STATE
 205                   |                               O - - - - - - - - - - >
 206                   |             do BLOCK probes <-O
 207                   |                               O   no peer?
 208                   |                               O  NOT_LINKED
 209                   |                               O - - - - - - - - - - >
 210                   |          gst_pad_get_range()  O
 211                   O<------------------------------O
 212                   O                               O
 213                   O flushing?                     O
 214                   O WRONG_STATE                   O
 215                   O- - - - - - - - - - - - - - - >O
 216  getrangefunc <---O                               O
 217                   O  flow error?                  O
 218                   O- - - - - - - - - - - - - - - >O
 219                   O                               O
 220  dp DATA probes <-O                               O
 221                   O- - - - - - - - - - - - - - - >O
 222                   |                               O
 223                   |              do IDLE probes <-O
 224                   |                               O   flow error?
 225                   |                               O - - - - - - - - - - >
 226                   |                               O
 227                   |              do DATA probes <-O
 228                   |                               O - - - - - - - - - - >
 229                   |                               |
 230