32cf3363fdbd11da7c44f1ae292bb6599fe9ee5a
[glsdk/gstreamer0-10.git] / docs / design / part-block.txt
1 Pad block
2 ---------
4 The purpose of blocking a pad is to be notified of downstream dataflow
5 and events. The notification can be used for
7  - (Re)connecting/disconnecting the pad.
8  - performing a seek 
9  - inspecting the data/events on the pad
11 The pad block is performed on a source pad (push based) or sink pad (pull based)
12 and will succeed when the following events happen on the pad:
14  - gst_pad_push()
15  - gst_pad_alloc_buffer()
16  - gst_pad_push_event() except for FLUSH_START and FLUSH_STOP events.
17  - gst_pad_pull_range () (on a sinkpad)
20 Flushing
21 --------
23  The flushing event is used to clear any data out of the
24  downstream elements.
26 * Generic case
28  Consider the following pipeline: 
30  .-----.      .-------.      .-------.
31  | src |      | elem1 |\/    | elem2 |
32  |    src -> sink    src -> sink    src ....
33  '-----'      '-------'/\    '-------'              
35  Where elem1.src is blocked. If the pad block is taken (the callback
36  is called or the sync block returned) no data is flowing in elem2.sink.
37  In this situation, the streaming thread is blocked on a GCond and is
38  waiting to be unblocked.
40  When sending a flushing seek upstream on elem1.src, the FLUSH_START and
41  will temporary unblock the streaming thread and make all pad functions that
42  triggers a block (_push/_alloc_buffer/_push_event/_pull_range) return
43  GST_FLOW_WRONG_STATE. This will then eventually pause the streaming thread
44  and release the STREAM_LOCK. 
45  
46  Since no STREAM lock is taken after the pad block it is not needed to send
47  the FLUSH_START event further downstream.
49  The FLUSH_STOP will set the srcpad to non-flushing again and is dropped 
50  fr the same reason. From then on, the new data after the flushing seek 
51  will be queued when the pad block is taken again.
53 * Case where the stream is blocking downstream
55  The example above is only valid if the elem1.src pad is really blocking
56  (callback called or sync block returned).
57  
58  In the case where the stream is blocking further downstream (on elem2.src
59  for example, or on a blocking queue), extra care has to be taken.
61  Consider the following pipeline:
63  .-----.      .-------.      .-------.
64  | src |      | elem1 |\/    | elem2 |
65  |    src -> sink    src -> sink    src .... Blocking somewhere downstream
66  '-----'      '-------'/\    '-------'              
68  A pad block has been requested by the user on elem1.src , but since the stream
69  is blocking somewhere downstream, the callback is not called or the sync block
70  does not return.
72  In order for the block to happen, a FLUSH_START needs to be sent directly on
73  the downstream blocking element/pad so that it releases the stream lock, and it
74  gives a chance for the elem1.src pad to block.
77 Use cases:
78 ----------
80 * Prerolling a partial pipeline
82  .---------.      .---------.                .----------.
83  | filesrc |      | demuxer |     .-----.    | decoder1 |
84  |        src -> sink      src1 ->|queue|-> sink       src 
85  '---------'      |         |     '-----'    '----------' X
86                   |         |                .----------.
87                   |         |     .-----.    | decoder2 |
88                   |        src2 ->|queue|-> sink       src
89                   '---------'     '-----'    '----------' X
92  The purpose is to create the pipeline dynamically up to the
93  decoders but not yet connect them to a sink and without losing
94  any data.
96  To do this, the source pads of the decoders is blocked so that no
97  events or buffers can escape and we don't interrupt the stream.
99  When all of the dynamic pad are created (no-more-pads emited by the
100  branching point, ie, the demuxer or the queues filled) and the pads
101  are blocked (blocked callback received) the pipeline is completely
102  prerolled.
104  It should then be possible to perform the following actions on the
105  prerolled pipeline:
107   - query duration/position
108   - perform a flushing seek to preroll a new position
109   - connect other elements and unblock the blocked pads.
112 * dynamically switching an element in a PLAYING pipeline.
115   .----------.      .----------.      .----------.
116   | element1 |      | element2 |      | element3 |
117  ...        src -> sink       src -> sink       ...
118   '----------'      '----------'      '----------'
119                     .----------.
120                     | element4 |
121                    sink       src                  
122                     '----------'                     
124  The purpose is to replace element2 with element4 in the PLAYING 
125  pipeline. 
127   1) block element1 src pad. This can be done async.
128   2) wait for block to happen. at this point nothing flowing between
129      element1 and element2 and nothing will flow until unblocked.
130   3) unlink element1 and element2
131   4) optional step: make sure data is flushed out of element2:
132      4a) pad event probe on element2 src
133      4b) send EOS to element2, this makes sure that element2 flushes
134          out the last bits of data it holds.
135      4c) wait for EOS to appear in the probe, drop the EOS.
136   5) unlink element2 and element3
137      5a) optionally element2 can now be set to NULL.
138   6) link element4 and element3
139   7) link element1 and element4 (FIXME, how about letting element4 know
140      about the currently running segment?, see issues.)
141   8) make sure element4 is in the same state as the rest of the elements. The
142      element should at least be PAUSED.
143   9) unblock element1 src
145  The same flow can be used to replace an element in a PAUSED pipeline. Only
146  special care has to be taken when performing step 2) which has to be done
147  async or it might deadlock. In the async callback one can then perform the
148  steps from 3). In a playing pipeline one can of course use the async block
149  as well, so that there is a generic method for both PAUSED and PLAYING.
151  The same flow works as well for any chain of multiple elements and might 
152  be implemented with a helper function in the future.
155 Issues
156 ------
158 When an EOS event has passed a pad and the pad is set to blocked, the block will
159 never happen because no data is going to flow anymore. One possibility is to
160 keep track of the pad's EOS state and make the block succeed immediatly. This is
161 not yet implemenented.
163 When dynamically reconnecting pads, some events (like NEWSEGMENT, EOS,
164 TAGS, ...) are not yet retransmitted to the newly connected element. It's
165 unclear if this can be done by core automatically by caching those events and
166 resending them on a relink. It might also be possible that this needs a
167 GstFlowReturn value from the event function, in which case the implementation
168 must be delayed for after 0.11, when we can break API/ABI.