docs/design/part-scheduling.txt

   1 Scheduling
   2 ----------
   3
   4 The scheduling in GStreamer is based on pads actively pushing (producing) data or
   5 pad pulling in data (consuming) from other pads.
   6
   7 Pushing
   8 ~~~~~~~
   9
  10 A pad can produce data and push it to the next pad. A pad that behaves this way
  11 exposes a loop function that will be called repeatedly until it returns false.
  12 The loop function is allowed to block whenever it wants. When the pad is deactivated
  13 the loop function should unblock though.
  14
  15 A pad operating in the push mode can only produce data to a pad that exposes a
  16 chain function. This chain function will be called with the buffer produced by
  17 the pushing pad.
  18
  19 This method of producing data is called the streaming mode since the producer
  20 produces a constant stream of data.
  21
  22 Pulling
  23 ~~~~~~~
  24
  25 Pads that operate in pulling mode can only pull data from a pad that exposes the
  26 pull_range function. In this case, the sink pad exposes a loop function that will be
  27 called repeatedly until the task is stopped.
  28
  29 After pulling data from the peer pad, the loop function will typically call the
  30 push function to push the result to the peer sinkpad.
  31
  32
  33 Deciding the scheduling mode
  34 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  35
  36 When a pad is activated, the _activate() function is called. The pad can then
  37 choose to activate itself in push or pull mode depending on upstream
  38 capabilities.
  39
  40 The GStreamer core will by default activate pads in push mode when there is no
  41 activate function for the pad.
  42
  43 The chain function
  44 ~~~~~~~~~~~~~~~~~~
  45
  46 The chain function will be called when a upstream element performs a _push() on the pad.
  47 The upstream element can be another chain based element or a pushing source.
  48
  49 The getrange function
  50 ~~~~~~~~~~~~~~~~~~~~~
  51
  52 The getrange function is called when a peer pad performs a _pull_range() on the pad. This
  53 downstream pad can be a pulling element or another _pull_range() based element.
  54
  55
  56 Scheduling Query
  57 ~~~~~~~~~~~~~~~~
  58
  59 A sinkpad can ask the upstream srcpad for its scheduling attributes. It does
  60 this with the SCHEDULING query.
  61
  62
  63  (out) "modes", G_TYPE_ARRAY (default NULL)
  64        - an array of GST_TYPE_PAD_MODE enums. Contains all the supported
  65          scheduling modes.
  66
  67  (out) "flags", GST_TYPE_SCHEDULING_FLAGS (default 0)
  68
  69      typedef enum {
  70        GST_SCHEDULING_FLAG_SEEKABLE      = (1 << 0),
  71        GST_SCHEDULING_FLAG_SEQUENTIAL    = (1 << 1)
  72      } GstSchedulingFlags;
  73
  74    _SEEKABLE:
  75        - the offset of a pull operation can be specified, if this flag is false,
  76          the offset should be -1,
  77
  78    _SEQUENTIAL:
  79        - suggest sequential access to the data. If _SEEKABLE is specified,
  80          seeks are allowed but should be avoided. This is common for network
  81          streams.
  82
  83  (out) "minsize", G_TYPE_INT (default 1)
  84        - the suggested minimum size of pull requests
  85
  86  (out) "maxsize", G_TYPE_INT (default -1, unlimited)
  87        - the suggested maximum size of pull requests
  88
  89  (out) "align", G_TYPE_INT (default 0)
  90        - the suggested alignment for the pull requests.
  91
  92
  93
  94 Plug-in techniques
  95 ~~~~~~~~~~~~~~~~~~
  96
  97 Multi-sink elements
  98 ^^^^^^^^^^^^^^^^^^^
  99
 100 Elements with multiple sinks can either expose a loop function on each of the pads to
 101 actively pull_range data or they can expose a chain function on each pad.
 102
 103 Implementing a chain function is usually easy and allows for all possible scheduling
 104 methods.
 105
 106 Pad select
 107 ----------
 108
 109   If the chain based sink wants to wait for one of the pads to receive a buffer, just
 110   implement the action to perform in the chain function. Be aware that the action could
 111   be performed in different threads and possibly simultaneously so grab the STREAM_LOCK.
 112
 113 Collect pads
 114 ------------
 115
 116   If the chain based sink pads all require one buffer before the element can operate on
 117   the data, collect all the buffers in the chain function and perform the action when
 118   all chainpads received the buffer.
 119
 120   In this case you probably also don't want to accept more data on a pad that has a buffer
 121   queued. This can easily be done with the following code snippet:
 122
 123     static GstFlowReturn _chain (GstPad *pad, GstBuffer *buffer)
 124     {
 125       LOCK (mylock);
 126       while (pad->store != NULL) {
 127         WAIT (mycond, mylock);
 128       }
 129       pad->store = buffer;
 130       SIGNAL (mycond);
 131       UNLOCK (mylock);
 132
 133       return GST_FLOW_OK;
 134     }
 135
 136     static void _pull (GstPad *pad, GstBuffer **buffer)
 137     {
 138       LOCK (mylock);
 139       while (pad->store == NULL) {
 140         WAIT (mycond, mylock);
 141       }
 142       **buffer = pad->store;
 143       pad->store = NULL;
 144       SIGNAL (mycond);
 145       UNLOCK (mylock);
 146     }
 147
 148
 149 Cases
 150 ~~~~~
 151
 152 Inside the braces below the pads is stated what function the
 153 pad support:
 154
 155   l: exposes a loop function, so it can act as a pushing source.
 156   g: exposes a getrange function
 157   c: exposes a chain function
 158
 159   following scheduling decisions are made based on the scheduling
 160   methods exposed by the pads:
 161
 162   (g) - (l): sinkpad will pull data from src
 163   (l) - (c): srcpad actively pushes data to sinkpad
 164   ()  - (c): srcpad will push data to sinkpad.
 165
 166   ()  - () : not schedulable.
 167   ()  - (l): not schedulable.
 168   (g) - () : not schedulable.
 169   (g) - (c): not schedulable.
 170   (l) - () : not schedulable.
 171   (l) - (l): not schedulable
 172
 173   ()  - (g): impossible
 174   (g) - (g): impossible.
 175   (l) - (g): impossible
 176   (c) - () : impossible
 177   (c) - (g): impossible
 178   (c) - (l): impossible
 179   (c) - (c): impossible
 180
 181  +---------+    +------------+    +-----------+
 182  | filesrc |    | mp3decoder |    | audiosink |
 183  |        src--sink         src--sink         |
 184  +---------+    +------------+    +-----------+
 185          (l-g) (c)           ()   (c)
 186
 187  When activating the pads:
 188
 189    * audiosink has a chain function and the peer pad has no
 190      loop function, no scheduling is done.
 191    * mp3decoder and filesrc expose an (l) - (c) connection,
 192      a thread is created to call the srcpad loop function.
 193
 194  +---------+    +------------+    +----------+
 195  | filesrc |    | avidemuxer |    | fakesink |
 196  |        src--sink         src--sink        |
 197  +---------+    +------------+    +----------+
 198          (l-g) (l)          ()   (c)
 199
 200    * fakesink has a chain function and the peer pad has no
 201      loop function, no scheduling is done.
 202    * avidemuxer and filesrc expose an (g) - (l) connection,
 203      a thread is created to call the sinkpad loop function.
 204
 205  +---------+    +----------+    +------------+    +----------+
 206  | filesrc |    | identity |    | avidemuxer |    | fakesink |
 207  |        src--sink       src--sink         src--sink        |
 208  +---------+    +----------+    +------------+    +----------+
 209          (l-g) (c)        ()   (l)          ()   (c)
 210
 211    * fakesink has a chain function and the peer pad has no
 212      loop function, no scheduling is done.
 213    * avidemuxer and identity expose no schedulable connection so
 214      this pipeline is not schedulable.
 215
 216  +---------+    +----------+    +------------+    +----------+
 217  | filesrc |    | identity |    | avidemuxer |    | fakesink |
 218  |        src--sink       src--sink         src--sink        |
 219  +---------+    +----------+    +------------+    +----------+
 220          (l-g) (c-l)      (g)  (l)          ()   (c)
 221
 222    * fakesink has a chain function and the peer pad has no
 223      loop function, no scheduling is done.
 224    * avidemuxer and identity expose an (g) - (l) connection,
 225      a thread is created to call the sinkpad loop function.
 226    * identity knows the srcpad is getrange based and uses the
 227      thread from avidemux to getrange data from filesrc.
 228
 229  +---------+    +----------+    +------------+    +----------+
 230  | filesrc |    | identity |    | oggdemuxer |    | fakesink |
 231  |        src--sink       src--sink         src--sink        |
 232  +---------+    +----------+    +------------+    +----------+
 233          (l-g) (c)        ()   (l-c)        ()   (c)
 234
 235    * fakesink has a chain function and the peer pad has no
 236      loop function, no scheduling is done.
 237    * oggdemuxer and identity expose an () - (l-c) connection,
 238      oggdemux has to operate in chain mode.
 239    * identity chan only work chain based and so filesrc creates
 240      a thread to push data to identity.
 241
 242