markdown/design/activation.md

   1 # Pad (de)activation
   2
   3 ## Activation
   4
   5 When changing states, a bin will set the state on all of its children in
   6 sink-to-source order. As elements undergo the READY→PAUSED transition,
   7 their pads are activated so as to prepare for data flow. Some pads will
   8 start tasks to drive the data flow.
   9
  10 An element activates its pads from sourcepads to sinkpads. This to make
  11 sure that when the sinkpads are activated and ready to accept data, the
  12 sourcepads are already active to pass the data downstream.
  13
  14 Pads can be activated in one of two modes, PUSH and PULL. PUSH pads are
  15 the normal case, where the source pad in a link sends data to the sink
  16 pad via `gst_pad_push()`. PULL pads instead have sink pads request data
  17 from the source pads via `gst_pad_pull_range()`.
  18
  19 To activate a pad, the core will call `gst_pad_set_active()` with a
  20 TRUE argument, indicating that the pad should be active. If the pad is
  21 already active, be it in a PUSH or PULL mode, `gst_pad_set_active()`
  22 will return without doing anything. Otherwise it will call the
  23 activation function of the pad.
  24
  25 Because the core does not know in which mode to activate a pad (PUSH or
  26 PULL), it delegates that choice to a method on the pad, `activate()`. The
  27 `activate()` function of a pad should choose whether to operate in PUSH or
  28 PULL mode. Once the choice is made, it should call `activate_mode()` with
  29 the selected activation mode. The default `activate()` function will call
  30 `activate_mode()` with `#GST_PAD_MODE_PUSH`, as it is the default
  31 mechanism for data flow. A sink pad that supports either mode of
  32 operation might call `activate_mode(PULL)` if the SCHEDULING query
  33 upstream contains the `#GST_PAD_MODE_PULL` scheduling mode, and
  34 `activate_mode(PUSH)` otherwise.
  35
  36 Consider the case `fakesrc ! fakesink`, where fakesink is configured to
  37 operate in PULL mode. State changes in the pipeline will start with
  38 fakesink, which is the most downstream element. The core will call
  39 `activate()` on fakesink’s sink pad. For fakesink to go into PULL mode, it
  40 needs to implement a custom `activate()` function that will call
  41 `activate_mode(PULL)` on its sink pad (because the default is to use PUSH
  42 mode). `activate_mode(PULL)` is then responsible for starting the task
  43 that pulls from fakesrc:src. Clearly, fakesrc needs to be notified that
  44 fakesrc is about to pull on its src pad, even though the pipeline has
  45 not yet changed fakesrc’s state. For this reason, GStreamer will first
  46 call call `activate_mode(PULL)` on fakesink:sink’s peer before calling
  47 `activate_mode(PULL)` on fakesink:sinks.
  48
  49 In short, upstream elements operating in PULL mode must be ready to
  50 produce data in READY, after having `activate_mode(PULL)` called on their
  51 source pad. Also, a call to `activate_mode(PULL)` needs to propagate
  52 through the pipeline to every pad that a `gst_pad_pull()` will reach. In
  53 the case `fakesrc ! identity ! fakesink`, calling `activate_mode(PULL)`
  54 on identity’s source pad would need to activate its sink pad in pull
  55 mode as well, which should propagate all the way to fakesrc.
  56
  57 If, on the other hand, `fakesrc ! fakesink` is operating in PUSH mode,
  58 the activation sequence is different. First, `activate()` on fakesink:sink
  59 calls `activate_mode(PUSH)` on fakesink:sink. Then fakesrc’s pads are
  60 activated: sources first, then sinks (of which fakesrc has none).
  61 fakesrc:src’s activation function is then called.
  62
  63 Note that it does not make sense to set an activation function on a
  64 source pad. The peer of a source pad is downstream, meaning it should
  65 have been activated first. If it was activated in PULL mode, the source
  66 pad should have already had `activate_mode(PULL)` called on it, and thus
  67 needs no further activation. Otherwise it should be in PUSH mode, which
  68 is the choice of the default activation function.
  69
  70 So, in the PUSH case, the default activation function chooses PUSH mode,
  71 which calls `activate_mode(PUSH)`, which will then start a task on the
  72 source pad and begin pushing. In this way PUSH scheduling is a bit
  73 easier, because it follows the order of state changes in a pipeline.
  74 fakesink is already in PAUSED with an active sink pad by the time
  75 fakesrc starts pushing data.
  76
  77 ## Deactivation
  78
  79 Pad deactivation occurs when its parent goes into the READY state or
  80 when the pad is deactivated explicitly by the application or element.
  81 `gst_pad_set_active()` is called with a FALSE argument, which then
  82 calls `activate_mode(PUSH)` or `activate_mode(PULL)` with a FALSE
  83 argument, depending on the current activation mode of the pad.
  84
  85 ## Mode switching
  86
  87 Changing from push to pull modes needs a bit of thought. This is
  88 actually possible and implemented but not yet documented here.