4 Both elements and pads can be in different states. The states of the pads are
5 linked to the state of the element so the design of the states is mainly
6 focused around the element states.
8 An element can be in 4 states. NULL, READY, PAUSED and PLAYING. When an element
9 is initially instantiated, it is in the NULL state.
15 - NULL: This is the initial state of an element.
16 - READY: The element should be prepared to go to PAUSED.
17 - PAUSED: The element should be ready to accept and process data. Sink
18 elements however only accept one buffer and then block.
19 - PLAYING: The same as PAUSED except for live sources and sinks. Sinks accept
20 and rendering data. Live sources produce data.
22 We call the sequence NULL->PLAYING an upwards state change and PLAYING->NULL
23 a downwards state change.
29 the following state changes are possible:
32 - The element must check if the resources it needs are available.
33 Device sinks and -sources typically try to probe the device to constrain
35 - The element opens the device, this is needed if the previous step requires
36 the device to be opened.
39 - The element pads are activated in order to receive data in PAUSED.
40 Streaming threads are started.
41 - Some elements might need to return ASYNC and complete the state change
42 when they have enough information. It is a requirement for sinks to
43 return ASYNC and complete the state change when they receive the first
44 buffer or EOS event (preroll). Sinks also block the dataflow when in PAUSED.
45 - A pipeline resets the running_time to 0.
46 - Live sources return NO_PREROLL and don't generate data.
49 - Most elements ignore this state change.
50 - The pipeline selects a clock and distributes this to all the children
51 before setting them to PLAYING. This means that it is only alowed to
52 synchronize on the clock in the PLAYING state.
53 - The pipeline uses the clock and the running_time to calculate the base_time.
54 The base_time is distributed to all children when performing the state
56 - Sink elements stop blocking on the preroll buffer or event and start
58 - Sinks can post the EOS message in the PLAYING state. It is not allowed to
59 post EOS when not in the PLAYING state.
60 - While streaming in PAUSED or PLAYING elements can create and remove
62 - Live sources start generating data and return SUCCESS.
65 - Most elements ignore this state change.
66 - The pipeline calculates the running_time based on the last selected clock
67 and the base_time. It stores this information to continue playback when
68 going back to the PLAYING state.
69 - Sinks unblock any clock wait calls.
70 - When a sink does not have a pending buffer to play, it returns ASYNC from
71 this state change and completes the state change when it receives a new
72 buffer or an EOS event.
73 - Any queued EOS messages are removed since they will be reposted when going
74 back to the PLAYING state. The EOS messages are queued in GstBins.
75 - Live sources stop generating data and return NO_PREROLL.
78 - Sinks unblock any waits in the preroll.
79 - Elements unblock any waits on devices
80 - Chain or get_range functions return WRONG_STATE.
81 - The element pads are deactivated so that streaming becomes impossible and
82 all streaming threads are stopped.
83 - The sink forgets all negotiated formats
84 - Elements remove all sometimes pads
87 - Elements close devices
88 - Elements reset any internal state.
94 An element has 4 state variables that are protected with the object LOCK:
101 The STATE always reflects the current state of the element.
102 The STATE_NEXT reflects the next state the element will go to.
103 The STATE_PENDING always reflects the required state of the element.
104 The STATE_RETURN reflects the last return value of a state change.
106 The STATE_NEXT and STATE_PENDING can be VOID_PENDING if the element is in
109 An element has a special lock to protect against concurrent invocations of
110 _set_state(), called the STATE_LOCK.
113 Setting state on elements
114 -------------------------
116 The state of an element can be changed with _element_set_state(). When chaning
117 the state of an element all intermediate states will also be set on the element
118 until the final desired state is set.
120 The _set_state() function can return 3 possible values:
122 GST_STATE_FAILURE: The state change failed for some reason. The plugin should
123 have posted an error message on the bus with information.
125 GST_STATE_SUCCESS: The state change is completed successfully.
127 GST_STATE_ASYNC: The state change will complete later on. This can happen
128 When the element needs a long time to perform the state
129 change or for sinks that need to receive the first buffer
130 before they can complete the state change (preroll).
132 GST_STATE_NO_PREROLL: The state change is completed successfully but the element
133 will not be able to produce data in the PAUSED state.
135 In the case of an ASYNC state change, it is possible to proceed to the next
136 state before the current state change completed, however, the element will only
137 get to this next state before completing the previous ASYNC state change.
138 After receiving an ASYNC return value, you can use _element_get_state() to poll
139 the status of the element. If the polling returns SUCCESS, the element completed
140 the state change to the last requested state with _set_state().
142 When setting the state of an element, the STATE_PENDING is set to the required
143 state. Then the state change function of the element is called and the result of
144 that function is used to update the STATE and STATE_RETURN fields, STATE_NEXT,
145 STATE_PENDING and STATE_RETURN fields. If the function returned ASYNC, this result
146 is immediatly returned to the caller.
149 Getting state of elements
150 -------------------------
152 The _get_state() function takes 3 arguments, two pointers that will hold the
153 current and pending state and one GstClockTime that holds a timeout value. The
154 function returns a GstElementStateReturn.
156 - If the element returned SUCCESS to the previous _set_state() function, this
157 function will return the last state set on the element and VOID_PENDING in
158 the pending state value. The function returns GST_STATE_SUCCESS.
160 - If the element returned NO_PREROLL to the previous _set_state() function, this
161 function will return the last state set on the element and VOID_PENDING in
162 the pending state value. The function returns GST_STATE_NO_PREROLL.
164 - If the element returned FAILURE to the previous _set_state() call, this
165 funciton will return FAILURE with the state set to the current state of
166 the element and the pending state set to the value used in the last call
169 - If the element returned ASYNC to the previous _set_state() call, this function
170 will wait for the element to complete its state change up to the amount of time
171 specified in the GstClockTime.
173 * If the element does not complete the state change in the specified amount of
174 time, this function will return ASYNC with the state set to the current state
175 and the pending state set to the pending state.
177 * If the element completes the state change within the specified timeout, this
178 function returns the updated state and VOID_PENDING as the pending state.
180 * If the element aborts the ASYNC state change due to an error within the
181 specified timeout, this function returns FAILURE with the state set to last
182 successfull state and pending set to the last attempt. The element should
183 also post an error message on the bus with more information about the problem.
189 A GstBin manages the state of its children. It does this by propagating the state
190 changes performed on it to all of its children. The _set_state() function on a
191 bin will call the _set_state() function on all of its children, that are
192 not already in the target state or in a change state to the target state.
194 The children are iterated from the sink elements to the source elements. This makes
195 sure that when changing the state of an element, the downstream elements are in
196 the correct state to process the eventual buffers. In the case of a downwards
197 state change, the sink elements will shut down first which makes the upstream
198 elements shut down as well since the _push() function returns a GST_FLOW_WRONG_STATE
201 If all the children return SUCCESS, the function returns SUCCESS as well.
203 If one of the children returns FAILURE, the function returns FAILURE as well. In
204 this state it is possible that some elements successfuly changed state. The
205 application can check which elements have a changed state, which were in error
206 and which were not affected by iterating the elements and calling _get_state()
209 If after calling the state function on all children, one of the children returned
210 ASYNC, the function returns ASYNC as well.
212 If after calling the state function on all children, one of the children returned
213 NO_PREROLL, the function returns NO_PREROLL as well.
215 If both NO_PREROLL and ASYNC children are present, NO_PREROLL is returned.
217 The current state of the bin can be retrieved with _get_state().
219 If the bin is performing an ASYNC state change, it will automatically update its
220 current state fields when it receives state messages from the children.
223 Implementing states in elements
224 -------------------------------
234 Upward state changes always return ASYNC either if the STATE_PENDING is
244 - element commits state ASYNC
247 - update STATE_PENDING state
249 - no change_state called on element
253 A->B: all elements SUCCESS
256 A->B: some elements ASYNC
258 - listen for commit messages on bus
259 - for each commit message, poll elements, this happens in another
261 - if no ASYNC elements, commit state, continue state change
264 downward state change
265 ----------------------
267 Downward state changes only return ASYNC if the final state is ASYNC.
268 This is to make sure that it's not needed to wait for an element to
269 complete the preroll or other ASYNC state changes when one only wants to
270 shut down an element.
277 A -> B => ASYNC not final state
278 - commit state on behalf of element
280 A -> B => ASYNC final state
281 - element will commit ASYNC
288 A -> B -> ASYNC not final state
289 - commit state on behalf of element, continue state change
291 A -> B => ASYNC final state
293 - listen for commit messages on bus
294 - for each commit message, poll elements
295 - if no ASYNC elements, commit state
298 Locking overview (element)
299 --------------------------
301 * Element commiting SUCCESS
303 - STATE_LOCK is taken in set_state
304 - change state is called if SUCCESS, commit state is called
305 - commit state calls change_state to next state change.
306 - if final state is reached, stack unwinds and result is returned to
307 set_state and caller.
310 set_state(element) change_state (element) commit_state
316 |------------------------>| |
319 | | (do state change) |
323 | |---------------------->|
326 | |<----------------------| if (!final) change_state (next)
331 |<------------------------| |
340 * Element commiting ASYNC
342 - STATE_LOCK is taken in set_state
343 - change state is called and returns ASYNC
344 - ASYNC returned to the caller.
345 - element takes LOCK in streaming thread.
346 - element calls commit_state in streaming thread.
347 - commit state calls change_state to next state change.
350 set_state(element) change_state (element) stream_thread commit_state (element)
356 |------------------------>| | |
363 |<------------------------| | |
364 | ASYNC STREAM_UNLOCK |
366 | .....sync........ STATE_LOCK |
367 ASYNC |----------------->|
369 | |---> post_message()
370 | |---> if (!final) change_state (next)
379 *********************************************
380 *********************************************
382 set_state cannot be called from multiple threads at the same time. The STATE_LOCK
385 state variables are protected with the LOCK.
387 calling set_state while gst_state is called should unlock the get_state with
388 an error. The cookie will do that.
396 update current, next, pending state