docs/design/part-states.txt

   1 States
   2 ======
   3
   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.
   7
   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.
  10
  11
  12 State definitions
  13 -----------------
  14
  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 sinks, who are now accepting
  20             and rendering data.
  21
  22 We call the sequence NULL->PLAYING an upwards state change and PLAYING->NULL
  23 a downwards state change.
  24
  25
  26 State transitions
  27 -----------------
  28
  29 the following state changes are possible:
  30
  31  NULL -> READY
  32    - The element must check if the resources it needs are available.
  33      Audiosinks typically try to probe the device.
  34
  35  READY -> PAUSED
  36    - The element opens the device and prepares itself for PLAYING.
  37    - the element pads are activated in order to receive data in PAUSED.
  38      streaming threads are started.
  39    - some elements might need to return ASYNC and complete the state change
  40      when they have enough information. It is a requirement for sinks to
  41      return ASYNC and complete the state change when they receive the first
  42      buffer or EOS event (prerol). Sinks also block the dataflow when in PAUSED.
  43    - a pipeline resets the stream time to 0.
  44    - live sources return NO_PREROLL and don't generate data.
  45
  46  PAUSED -> PLAYING
  47    - most elements ignore this state change.
  48    - The pipeline selects a clock and distributes this to all the children
  49      before setting them to PLAYING. This means that it is only alowed to
  50      synchronize on the clock in the PLAYING state.
  51    - The pipeline uses the clock and the stream time to calculate the base time.
  52      The base time is distributed to all children when performing the state
  53      change.
  54    - sink elements stop blocking on the preroll buffer or event and start
  55      rendering the data.
  56    - sinks can post the EOS message in the PLAYING state. It is not allowed to
  57      post EOS when not in the PLAYING state.
  58    - while streaming in PAUSED or PLAYING elements can create and remove
  59      dynamic pads.
  60    - live sources start generating data and return SUCCESS.
  61
  62  PLAYING -> PAUSED
  63    - most elements ignore this state change.
  64    - The pipeline calculates the stream time based on the last selected clock
  65      and the base time. It stores this information to continue playback when
  66      going back to the PLAYING state.
  67    - sinks unblock any clock wait calls.
  68    - sinks return ASYNC from this state change and complete the state change
  69      when they receive a buffer or an EOS event.
  70    - any queued EOS messages are removed since they will be reposted when going
  71      back to the PLAYING state.
  72    - live sources stop generating data and return NO_PREROLL.
  73
  74  PAUSED -> READY
  75    - sinks unblock any waits in the preroll.
  76    - elements unblock any waits on devices
  77    - the element pads are deactivated so that streaming becomes impossible and
  78      all streaming threads are stopped.
  79
  80  READY -> NULL
  81    - element removes any dynamically created pads
  82
  83
  84 State variables
  85 ---------------
  86
  87 An element has a special lock to manage the state changes. This lock is called
  88 the STATE_LOCK.
  89
  90 The STATE_LOCK protects 3 element variables:
  91
  92   - STATE
  93   - STATE_NEXT
  94   - STATE_PENDING
  95   - STATE_RETURN
  96
  97 The STATE always reflects the current state of the element.
  98 The STATE_NEXT reflects the next state the element will go to.
  99 The STATE_PENDING always reflects the required state of the element.
 100 The STATE_RETURN reflects the last return value of a state change.
 101
 102 The STATE_NEXT and STATE_PENDING can be VOID_PENDING if the element is in
 103 the right state.
 104
 105 Setting state on elements
 106 -------------------------
 107
 108 The state of an element can be changed with _element_set_state(). When chaning
 109 the state of an element all intermediate states will also be set on the element
 110 until the final desired state is set.
 111
 112 The _set_state() function can return 3 possible values:
 113
 114   GST_STATE_FAILURE: The state change failed for some reason. The plugin should
 115                      have posted an error message on the bus with information.
 116
 117   GST_STATE_SUCCESS: The state change is completed successfully.
 118
 119   GST_STATE_ASYNC:   The state change will complete later on. This can happen
 120                      When the element needs a long time to perform the state
 121                      change or for sinks that need to receive the first buffer
 122                      before they can complete the state change (preroll).
 123
 124   GST_STATE_NO_PREROLL: The state change is completed successfully but the element
 125                      will not be able to produce data in the PAUSED state.
 126
 127 In the case of an async state change, it is possible to proceed to the next
 128 state before the current state change completed, however, the element will only
 129 get to this next state before completing the previous ASYNC state change.
 130 After receiving an ASYNC return value, you can use _element_get_state() to poll
 131 the status of the element. If the polling returns SUCCESS, the element completed
 132 the state change to the last requested state with _set_state().
 133
 134 When setting the state of an element, the STATE_PENDING is set to the required
 135 state. Then the state change function of the element is called and the result of
 136 that function is used to update the STATE and STATE_RETURN fields, STATE_NEXT,
 137 STATE_PENDING and STATE_RETURN fields. If the function returned ASYNC, this result
 138 is immediatly returned to the caller.
 139
 140
 141 Getting state of elements
 142 -------------------------
 143
 144 The _get_state() function takes 3 arguments, two pointers that will hold the
 145 current and pending state and one GTimeVal that holds a timeout value. The
 146 function returns a GstElementStateReturn.
 147
 148  - If the element returned SUCCESS to the previous _set_state() function, this
 149    function will return the last state set on the element and VOID_PENDING in
 150    the pending state value. The function returns GST_STATE_SUCCESS.
 151
 152  - If the element returned NO_PREROLL to the previous _set_state() function, this
 153    function will return the last state set on the element and VOID_PENDING in
 154    the pending state value. The function returns GST_STATE_NO_PREROLL.
 155
 156  - If the element returned FAILURE to the previous _set_state() call, this
 157    funciton will return FAILURE with the state set to the current state of
 158    the element and the pending state set to the value used in the last call
 159    of _set_state().
 160
 161  - If the element returned ASYNC to the previous _set_state() call, this function
 162    will wait for the element to complete its state change up to the amount of time
 163    specified in the GTimeVal.
 164
 165    * If the element does not complete the state change in the specified amount of
 166      time, this function will return ASYNC with the state set to the current state
 167      and the pending state set to the pending state.
 168
 169    * If the element completes the state change within the specified timeout, this
 170      function returns the updated state and VOID_PENDING as the pending state.
 171
 172    * If the element aborts the ASYNC state change due to an error within the
 173      specified timeout, this function returns FAILURE with the state set to last
 174      successfull state and pending set to the last attempt. The element should
 175      also post an error message on the bus with more information about the problem.
 176
 177
 178 States in GstBin
 179 ----------------
 180
 181 A GstBin manages the state of its children. It does this by propagating the state
 182 changes performed on it to all of its children.  The _set_state() function on a
 183 bin will call the _set_state() function on all of its children.
 184
 185 The children are iterated from the sink elements to the source elements. This makes
 186 sure that when changing the state of an element, the downstream elements are in
 187 the correct state to process the eventual buffers. In the case of a downwards
 188 state change, the sink elements will shut down first which makes the upstream
 189 elements shut down as well since the _push() function returns a GST_FLOW_WRONG_STATE
 190 error.
 191
 192 If all the children return SUCCESS, the function returns SUCCESS as well.
 193
 194 If one of the children returns FAILURE, the function returns FAILURE as well. In
 195 this state it is possible that some elements successfuly changed state. The
 196 application can check which elements have a changed state, which were in error
 197 and which were not affected by iterating the elements and calling _get_state()
 198 on the elements.
 199
 200 If after calling the state function on all children, one of the children returned
 201 ASYNC, the function returns ASYNC as well.
 202
 203 If after calling the state function on all children, one of the children returned
 204 NO_PREROLL, the function returns NO_PREROLL as well.
 205
 206 The current state of the bin can be retrieved with _get_state().
 207
 208 If the bin is performing an ASYNC state change, it will automatically update its
 209 current state fields when it receives state messages from the children.
 210
 211
 212 Implementing states in elements
 213 -------------------------------
 214
 215 READY
 216 -----
 217
 218
 219
 220 upward state change
 221 -------------------
 222
 223 Upward state changes always return ASYNC either if the STATE_PENDING is
 224 reached or not.
 225
 226 Element:
 227
 228   A -> B => SUCCESS
 229     - commit state
 230
 231   A -> B => ASYNC
 232     - no commit state
 233     - element commits state ASYNC
 234
 235   A -> B while ASYNC
 236     - update STATE_PENDING state
 237     - no commit state
 238     - no change_state called on element
 239
 240 Bin:
 241
 242   A->B: all elements SUCCESS
 243     - commit state
 244
 245   A->B: some elements ASYNC
 246     - no commit state
 247     - listen for commit messages on bus
 248     - for each commit message, poll elements
 249     - if no ASYNC elements, commit state, continue state change
 250       to STATE_PENDING
 251
 252 downward state change
 253 ----------------------
 254
 255 Downward state changes only return ASYNC if the final state is ASYNC.
 256 This is to make sure that it's not needed to wait for an element to
 257 complete the preroll or other ASYNC state changes when one only wants to
 258 shut down an element.
 259
 260 Element:
 261
 262   A -> B => SUCCESS
 263     - commit state
 264
 265   A -> B => ASYNC not final state
 266     - commit state on behalf of element
 267
 268   A -> B => ASYNC final state
 269     - element will commit ASYNC
 270
 271 Bin:
 272
 273   A -> B -> SUCCESS
 274     - commit state
 275
 276   A -> B -> ASYNC not final state
 277     - commit state on behalf of element, continue state change
 278
 279   A -> B => ASYNC final state
 280     - no commit state
 281     - listen for commit messages on bus
 282     - for each commit message, poll elements
 283     - if no ASYNC elements, commit state
 284
 285
 286 Locking overview (element)
 287 --------------------------
 288
 289  set_state(element)       change_state (element)     stream_thread      commit_state (element)
 290
 291       |                         |                          |                  |
 292       |                         |                          |                  |
 293   STATE_LOCK                    |                          |                  |
 294       |                         |                          |                  |
 295       |------------------------>|                          |                  |
 296       |                         |                          |                  |
 297       |                         |                          |                  |
 298       |                         | (start_task)             |                  |
 299       |                         |                          |                  |
 300       |                         |                     STREAM_LOCK             |
 301       |                         |                          |                  |
 302       |<------------------------|                          |                  |
 303       |     ASYNC                                          |                  |
 304   STATE_UNLOCK                                             |                  |
 305       |                .....sync........               STATE_LOCK             |
 306     ASYNC                                                  |----------------->|
 307                                                            |                  |
 308                                                            |                  |---> post_message(ASYNC)
 309                                                            |                  |---> if (!final) change_state (next)
 310                                                            |                  |     else SIGNAL
 311                                                            |<-----------------|
 312                                                        STATE_UNLOCK
 313                                                            |
 314                                                       STREAM_UNLOCK
 315
 316
 317
 318
 319
 320
 321