docs/random/wtay/eos-19012001

   1 OUTDATED
   2 --------
   3
   4 EOS as implemented on Jan 21 2001:
   5
   6 1) terminology
   7 --------------
   8
   9 EOS: end of stream. The problem we are trying to solve here is
  10      detecting when the processing of a piece of media data has
  11      ended.
  12
  13      This problem can get complicated because the pipeline might
  14      contain an arbitrary number of threads and other ASYNC and
  15      DECOUPLED elements like queues. We are trying to solve the
  16      obvious cases first by making some assumptions (see limitations)
  17      in order to avoid the exponentially growing complexity.
  18
  19      The trick is to detect when all the elements/subbins/threads
  20      and done processing their data. This involves monitoring the
  21      threads and elements.
  22
  23      Catching the EOS signals from an element is easy. We are focusing
  24      here on the EOS signal propagation to the manager bin up to the
  25      toplevel bin.
  26
  27 EOS call: the pads have a method gst_pad_set_eos () that will
  28      be called by an element that cannot send any more data on the
  29      pad.
  30
  31 EOS signals: elements fires the EOS signal when all it's pads are in
  32     EOS.
  33
  34 chains: at plan generation, the bin will find the elements it has to
  35     manage. The elements that are managed together are called a chain.
  36     This is typically a set of elements that need input from their
  37     peer element before they can output data. When one of those elements
  38     cannot provide more data and goes into EOS, the other elements
  39     are basically worthless and there is no point in trying to schedule
  40     them anymore.
  41
  42     Chains are typically broken up on DECOUPLED elements. Those elements
  43     have no clear relation between their input/output behaviour, like
  44     the queue.
  45
  46 EOS denial: An element can deny an EOS call by returning FALSE on the
  47     overridden EOS call. This behaviour is typical for an element that
  48     performs _get_region on its sinkpad and basically does not care
  49     about the EOS because it knows it will pull a specific region
  50     anyway.
  51
  52
  53 2) EOS implementation
  54 ---------------------
  55
  56 EOS is currently implemented by selectively disabling scheduling of
  57 the chains. This procedure continues untill a bin/thread has no more
  58 chains left to schedule, at which point it will fire the EOS signal.
  59
  60 A gboolean was added to the chain structure to indicate if this chain
  61 need scheduling. Initially this will gboolean will be set to TRUE.
  62
  63 the gst_bin_iterate_func will only schedule those chains that have
  64 their need_scheduling flag to TRUE.
  65
  66 All elements are treated as potential EOS signal providers. When we add
  67 the elements to a chain, we attach the eos signal to them and hand
  68 the chain they were added to as an argument to the signal handler.
  69 When an element goes to EOS, we mark the chain as need_scheduling=FALSE.
  70 This removes the chain from the scheduling loop.
  71
  72 Since plain bins in bins are flattened during the chain creation, we do
  73 not need to worry about the bin EOS.
  74
  75 Other elements that do their own managing (like threads) are treated
  76 differently, they are added to a list of EOS-providers. Since they
  77 have their own chains and use the same iterate_func, they will eventually
  78 fire EOS on their own when they run out of schedulable chains.
  79 The EOS signal of the EOS providers is caught by the parent bin which
  80 will then remove the bin from the list of possible EOS providers.
  81
  82 Combining the EOS providers list and the chains, the bin will fire
  83 and EOS signal when 1) it has no more chains to schedule, 2) all its
  84 EOS providers have signaled EOS.
  85
  86 3) queue EOS handling
  87 ---------------------
  88
  89 The queue overrides the eos call and performs the following:
  90
  91 Set the sinkpad to EOS and signal its internal g_cond to unlock any
  92 waiting threads on the srcpad.
  93
  94 The scrpad _get function performs the EOS call when no more buffers
  95 are queued and the sinkpad is in EOS. This causes the EOS call to
  96 propagate downstream and effectively causes all chains and threads
  97 to become EOS.
  98
  99
 100 4) limitations
 101 --------------
 102
 103 We assume a chain is a single schedualable entity. Rescheduling of
 104 the bins and chains are not performed.
 105
 106 No provisions for changing the state of the elements in EOS, although
 107 this probably isn't hard to do.
 108
 109 No provisions for undoing the EOS state. This is probably related to
 110 the state change, where a chain should become schedulable again when the
 111 element goes back to the PLAYING state.
 112
 113