From 89683e526e4ed00f5c2683a687ad84d161dbee82 Mon Sep 17 00:00:00 2001 From: Andy Wingo Date: Mon, 27 Jun 2005 13:25:44 +0000 Subject: [PATCH] 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 * docs/design/part-activation.txt: Notes on how activation should work -- not quite implemented yet. --- ChangeLog | 5 +++ docs/design/part-activation.txt | 82 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 87 insertions(+) create mode 100644 docs/design/part-activation.txt diff --git a/ChangeLog b/ChangeLog index 1bb0118..a044ded 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2005-06-27 Andy Wingo + + * docs/design/part-activation.txt: Notes on how activation should + work -- not quite implemented yet. + 2005-06-25 Wim Taymans * gst/gstghostpad.c: (gst_proxy_pad_do_chain): diff --git a/docs/design/part-activation.txt b/docs/design/part-activation.txt new file mode 100644 index 0000000..f2aa75c --- /dev/null +++ b/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. -- 2.7.4