docs/design/part-activation.txt: Notes on how activation should work -- not quite implemented yet.

Original commit message from CVS:
2005-06-27  Andy Wingo  <wingo@pobox.com>

* docs/design/part-activation.txt: Notes on how activation should
work -- not quite implemented yet.

ChangeLog

@@ -1,3 +1,8 @@
+2005-06-27  Andy Wingo  <wingo@pobox.com>
+
+	* docs/design/part-activation.txt: Notes on how activation should
+	work -- not quite implemented yet.
+
 2005-06-25  Wim Taymans  <wim@fluendo.com>
 
 	* gst/gstghostpad.c: (gst_proxy_pad_do_chain):

docs/design/part-activation.txt

@@ -0,0 +1,82 @@
+Pad activation
+--------------
+
+When changing states, a bin will set the state on all of its children in
+sink-to-source order. As elements undergo the READY->PAUSED transition,
+their pads are activated so as to prepare for data flow. Some pads will
+start tasks to drive the data flow.
+
+Pads can be activated in one of two modes, PUSH and PULL. PUSH pads are
+the normal case, where the source pad in a link sends data to the sink
+pad via gst_pad_push(). PULL pads instead have sink pads request data
+from the source pads via gst_pad_pull_range().
+
+To activate a pad, the core will call gst_pad_set_active() with a TRUE
+argument, indicating that the pad should be active. If the pad is
+already active, be it in a PUSH or PULL mode, gst_pad_set_active() will
+return without doing anything. Otherwise it will call the activation
+function of the pad.
+
+Because the core does not know in which mode to activate a pad (PUSH or
+PULL), it delegates that choice to a method on the pad, activate(). The
+activate() function of a pad should choose whether to operate in PUSH or
+PULL mode. Once the choice is made, it should call one of the two
+mode-specific activation functions, activate_push() or activate_pull().
+The default activate() function will call activate_push(), as it is the
+default mechanism for data flow. A sink pad that supports either mode of
+operation might call activate_pull() if calling check_get_range()
+returns TRUE, and activate_push() otherwise.
+
+Consider the case fakesrc ! fakesink, where fakesink is configured to
+operate in PULL mode. State changes in the pipeline will start with
+fakesink, which is the most downstream element. The core will call
+activate() on fakesink's sink pad. For fakesink to go into PULL mode, it
+needs to implement a custom activate() function that will call
+activate_pull() on its sink pad (because the default is to use PUSH
+mode). activate_pull() is then responsible for starting the task that
+pulls from fakesrc:src. Clearly, fakesrc needs to be notified that
+fakesrc is about to pull on its src pad, even though the pipeline has
+not yet changed fakesrc's state. For this reason, activate_pull() must
+first call activate_pull() on fakesink:sink's peer before starting
+fakesink's task.
+
+In short, upstream elements operating in PULL mode must be ready to
+produce data in READY, after having activate_pull() called on their
+source pad. Also, a call to activate_pull() needs to propagate through
+the pipeline to every pad that a gst_pad_pull() will reach. In the case
+fakesrc ! identity ! fakesink, calling activate_pull() on identity's
+source pad would need to activate its sink pad in pull mode as well,
+which should propagate all the way to fakesrc.
+
+If, on the other hand, fakesrc ! fakesink is operating in PUSH mode, the
+activation sequence is different. First, activate() on fakesink:sink
+calls activate_push() on fakesink:sink. Then fakesrc's pads are
+activated: sources first, then sinks (of which fakesrc has none).
+fakesrc:src's activation function is then called.
+
+Note that it does not make sense to set an activation function on a
+source pad. The peer of a source pad is downstream, meaning it should
+have been activated first. If it was activated in PULL mode, the the
+source pad should have already had activate_pull() called on it, and
+thus needs no further activation. Otherwise it should be in PUSH mode,
+which is the choice of the default activation function.
+
+So, in the PUSH case, the default activation function chooses PUSH mode,
+which calls activate_push(), which will then start a task on the source
+pad and begin pushing. In this way PUSH scheduling is a bit easier,
+because it follows the order of state changes in a pipeline. fakesink is
+already in PAUSED with an active sink pad by the time fakesrc starts
+pushing data.
+
+Deactivation
+------------
+
+Pad deactivation occurs when a pad is unlinked, or when its parent goes
+into the READY state. gst_pad_set_active() is called with a FALSE
+argument, which then calls activate_push() or activate_pull() with a
+FALSE argument, depending on the activation mode of the pad.
+
+Mode switching
+--------------
+
+Changing from push to pull modes needs a bit of thought.