docs/random/omega/sched-commit1

   1 Changed the way things are scheduled, especially sources.  A Src used to
   2 have a push() function, and optionally a pushregion() to deal with async
   3 reads, etc.  That whole thing has gone away, in favor of providing a
   4 pull() function for the output (Src) pad instead, ala chain functions.
   5 This makes constructing cothreaded schedules out of non-loop elements
   6 somewhat easier.  Basically there was always a question as to which pad
   7 was being dealt with.  In the pullregion case, cothread-specific data was
   8 used to try to pass the region struct to the right place, which is a slow
   9 hack.  And in general, the push function severely limited the kind of
  10 tricks that could be played when there's more than one output pad, such as
  11 a multi-out file reader with async capabilities on each pad independently.
  12
  13 This changes the way cothread scheduling occurs.  Instead of the hack to
  14 deal with Src's by calling their push() function (or optionally the
  15 pushregion(), in certain cases), we now are working towards a general
  16 mechanism where pads are the only thing that are dealt with directly.
  17
  18 An optimization was made in the process of doing this: the loopfunction
  19 actually run as the outer [stack] frame of the cothread is now set more
  20 intelligently in create_plan() based on what kind of element it is.  We
  21 now have:
  22
  23 loopfunc_wrapper: used for loop-based elements, it simply calls the
  24         loopfunc in a loop, paying attention to COTHREAD_STOPPING (see
  25         below).  It currently does other, soon to be depracated, stuff.
  26
  27 pullsrc_wrapper: wraps a Src that's not loop-based (since your options
  28         are now loop- or pull-based)
  29
  30 There will be a couple more to deal with other cases, such as Connections
  31 and chain-based elements.  The general idea is that it's a lot more
  32 efficient to make the decisions once in create_plan than to keep doing
  33 this huge if/else chain in the wrapper.  Just choose the right wrapper up
  34 front.  It'll be most apparent performance-wise in the case of whichever
  35 element context is switched to first for each iteration, since the whole
  36 wrapper setup is done for every iteration.
  37
  38 The tricky part is that there is now a bit of overloading of the function
  39 pointers in a pad.  The current meanings (possibly to change a bit more
  40 soon) are:
  41
  42 chainfunc: as always, chainfunc pointer is mirrored between peer pads
  43            (this may change, and the chain func may end up in pushfunc)
  44 pushfunc: SrcPad: gst_pad_pushfunc_proxy, cothread_switch to peer
  45           SinkPad: none (may take over chainfunc, see below) pullfunc:
  46 SrcPad: Src or Connection's function to construct buffers
  47           SinkPad: gst_pad_pullfunc_proxy, cothread_switch to peer
  48
  49 There are a number of issues remaining with the scheduling, not the least
  50 of which is the fact that Connections are still dealt with the old way,
  51 with _push() functions and such.  I'm trying to figure out a way to unify
  52 the system so it makes sense.  Following the scheduling system is hard
  53 enough, trying to change it is murder.
  54
  55
  56 Another useful scheduling addition, mentioned above, is COTHREAD_STOPPING.
  57 It's an element flag that's used to signal whatever code is running in
  58 cothread context that it should be finishing up and exiting soon.  An
  59 example of this is in plugins/cobin/spindentity.c.  All the loops should
  60 now be composed of do/while loops, rather than while(1) loops:
  61
  62   do {
  63     buf = gst_pad_pull(spindentity->sinkpad);
  64     gst_pad_push(spindentity->srcpad,buf);
  65   } while (!GST_ELEMENT_IS_COTHREAD_STOPPING(element));
  66
  67 The reason for this is that COTHREAD_STOPPING may be set before the above
  68 loop ever gets started.  It wouldn't do for the body of the loop to never
  69 once get called, that would simply stall the pipeline. Note that only the
  70 core library code is ever responsible for setting and unsetting this flag.
  71 All elements have to do is respond to it by cleanly exiting the loop and
  72 the function holding it.
  73
  74 This is needed primarily to allow iterations to occur properly.
  75 Basically, there's a single entry point in the cothread scheduling loop,
  76 gst_bin_iterate_func() simply switches to this cothread.  If the element
  77 in this context is allowed to loop infinitely, nothing would even switch
  78 back to the context from which the iterate() was originally called.  This
  79 is a bit of a problem.  The solution is for there to be an implicit switch
  80 back to the originating context.  Now, even I'm not sure exactly how this
  81 works, but if the cothread that's switched to actually returns, execution
  82 returns back to the calling context, i.e. iterate_func().
  83
  84 COTHREAD_STOPPING is therefore set just before switching into this
  85 (currently randomly chosen) context, on the assumption that it will return
  86 promptly after finishing its duties.  The burden of clearing the flag
  87 falls to the various wrapper functions provided by the Bin code, thus
  88 element writers don't have to worry about doing that at all (and simply
  89 shouldn't).
  90
  91
  92 Related changes:
  93 All the sources in elements/ have been changed to reflect the new system.
  94
  95
  96 FIXMEs:
  97 1) gstpipeline.c calls gst_src_push at some point, dunno why, it's
  98 commented out now.
  99 2) any other sources, including vcdsrc, dvdsrc, and v4lsrc will break
 100 badly and need to be modified to work as pull-based sources.