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 live sources and sinks. Sinks accept
  20             and rendering data. Live sources produce 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      Device sinks and -sources typically try to probe the device to constain
  34      their caps.
  35    - The element opens the device, this is needed if the previous step requires
  36      the device to be opened.
  37
  38  READY -> PAUSED
  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 (prerol). 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.
  47
  48  PAUSED -> PLAYING
  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
  55      change.
  56    - sink elements stop blocking on the preroll buffer or event and start
  57      rendering the data.
  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
  61      dynamic pads.
  62    - live sources start generating data and return SUCCESS.
  63
  64  PLAYING -> PAUSED
  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 did not have a pending buffer to play, it returns ASYNC from
  71      this state change and complete the state change when they receive a new buffer
  72      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.
  76
  77  PAUSED -> READY
  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
  85  READY -> NULL
  86    - elements close devices
  87    - element removes any dynamically created pads
  88
  89
  90 State variables
  91 ---------------
  92
  93 An element has 4 state variables that are protected with the object LOCK:
  94
  95   - STATE
  96   - STATE_NEXT
  97   - STATE_PENDING
  98   - STATE_RETURN
  99
 100 The STATE always reflects the current state of the element.
 101 The STATE_NEXT reflects the next state the element will go to.
 102 The STATE_PENDING always reflects the required state of the element.
 103 The STATE_RETURN reflects the last return value of a state change.
 104
 105 The STATE_NEXT and STATE_PENDING can be VOID_PENDING if the element is in
 106 the right state.
 107
 108 An element has a special lock to protect against concurrent invocations of
 109 _set_state(), called the STATE_LOCK.
 110
 111
 112 Setting state on elements
 113 -------------------------
 114
 115 The state of an element can be changed with _element_set_state(). When chaning
 116 the state of an element all intermediate states will also be set on the element
 117 until the final desired state is set.
 118
 119 The _set_state() function can return 3 possible values:
 120
 121   GST_STATE_FAILURE: The state change failed for some reason. The plugin should
 122                      have posted an error message on the bus with information.
 123
 124   GST_STATE_SUCCESS: The state change is completed successfully.
 125
 126   GST_STATE_ASYNC:   The state change will complete later on. This can happen
 127                      When the element needs a long time to perform the state
 128                      change or for sinks that need to receive the first buffer
 129                      before they can complete the state change (preroll).
 130
 131   GST_STATE_NO_PREROLL: The state change is completed successfully but the element
 132                      will not be able to produce data in the PAUSED state.
 133
 134 In the case of an ASYNC state change, it is possible to proceed to the next
 135 state before the current state change completed, however, the element will only
 136 get to this next state before completing the previous ASYNC state change.
 137 After receiving an ASYNC return value, you can use _element_get_state() to poll
 138 the status of the element. If the polling returns SUCCESS, the element completed
 139 the state change to the last requested state with _set_state().
 140
 141 When setting the state of an element, the STATE_PENDING is set to the required
 142 state. Then the state change function of the element is called and the result of
 143 that function is used to update the STATE and STATE_RETURN fields, STATE_NEXT,
 144 STATE_PENDING and STATE_RETURN fields. If the function returned ASYNC, this result
 145 is immediatly returned to the caller.
 146
 147
 148 Getting state of elements
 149 -------------------------
 150
 151 The _get_state() function takes 3 arguments, two pointers that will hold the
 152 current and pending state and one GstClockTime that holds a timeout value. The
 153 function returns a GstElementStateReturn.
 154
 155  - If the element returned SUCCESS to the previous _set_state() function, this
 156    function will return the last state set on the element and VOID_PENDING in
 157    the pending state value. The function returns GST_STATE_SUCCESS.
 158
 159  - If the element returned NO_PREROLL to the previous _set_state() function, this
 160    function will return the last state set on the element and VOID_PENDING in
 161    the pending state value. The function returns GST_STATE_NO_PREROLL.
 162
 163  - If the element returned FAILURE to the previous _set_state() call, this
 164    funciton will return FAILURE with the state set to the current state of
 165    the element and the pending state set to the value used in the last call
 166    of _set_state().
 167
 168  - If the element returned ASYNC to the previous _set_state() call, this function
 169    will wait for the element to complete its state change up to the amount of time
 170    specified in the GstClockTime.
 171
 172    * If the element does not complete the state change in the specified amount of
 173      time, this function will return ASYNC with the state set to the current state
 174      and the pending state set to the pending state.
 175
 176    * If the element completes the state change within the specified timeout, this
 177      function returns the updated state and VOID_PENDING as the pending state.
 178
 179    * If the element aborts the ASYNC state change due to an error within the
 180      specified timeout, this function returns FAILURE with the state set to last
 181      successfull state and pending set to the last attempt. The element should
 182      also post an error message on the bus with more information about the problem.
 183
 184
 185 States in GstBin
 186 ----------------
 187
 188 A GstBin manages the state of its children. It does this by propagating the state
 189 changes performed on it to all of its children.  The _set_state() function on a
 190 bin will call the _set_state() function on all of its children.
 191
 192 The children are iterated from the sink elements to the source elements. This makes
 193 sure that when changing the state of an element, the downstream elements are in
 194 the correct state to process the eventual buffers. In the case of a downwards
 195 state change, the sink elements will shut down first which makes the upstream
 196 elements shut down as well since the _push() function returns a GST_FLOW_WRONG_STATE
 197 error.
 198
 199 If all the children return SUCCESS, the function returns SUCCESS as well.
 200
 201 If one of the children returns FAILURE, the function returns FAILURE as well. In
 202 this state it is possible that some elements successfuly changed state. The
 203 application can check which elements have a changed state, which were in error
 204 and which were not affected by iterating the elements and calling _get_state()
 205 on the elements.
 206
 207 If after calling the state function on all children, one of the children returned
 208 ASYNC, the function returns ASYNC as well.
 209
 210 If after calling the state function on all children, one of the children returned
 211 NO_PREROLL, the function returns NO_PREROLL as well.
 212
 213 If both NO_PREROLL and ASYNC children are present, NO_PREROLL is returned.
 214
 215 The current state of the bin can be retrieved with _get_state().
 216
 217 If the bin is performing an ASYNC state change, it will automatically update its
 218 current state fields when it receives state messages from the children.
 219
 220
 221 Implementing states in elements
 222 -------------------------------
 223
 224 READY
 225 -----
 226
 227
 228
 229 upward state change
 230 -------------------
 231
 232 Upward state changes always return ASYNC either if the STATE_PENDING is
 233 reached or not.
 234
 235 Element:
 236
 237   A -> B => SUCCESS
 238     - commit state
 239
 240   A -> B => ASYNC
 241     - no commit state
 242     - element commits state ASYNC
 243
 244   A -> B while ASYNC
 245     - update STATE_PENDING state
 246     - no commit state
 247     - no change_state called on element
 248
 249 Bin:
 250
 251   A->B: all elements SUCCESS
 252     - commit state
 253
 254   A->B: some elements ASYNC
 255     - no commit state
 256     - listen for commit messages on bus
 257     - for each commit message, poll elements, this happens in another
 258       thread.
 259     - if no ASYNC elements, commit state, continue state change
 260       to STATE_PENDING
 261
 262 downward state change
 263 ----------------------
 264
 265 Downward state changes only return ASYNC if the final state is ASYNC.
 266 This is to make sure that it's not needed to wait for an element to
 267 complete the preroll or other ASYNC state changes when one only wants to
 268 shut down an element.
 269
 270 Element:
 271
 272   A -> B => SUCCESS
 273     - commit state
 274
 275   A -> B => ASYNC not final state
 276     - commit state on behalf of element
 277
 278   A -> B => ASYNC final state
 279     - element will commit ASYNC
 280
 281 Bin:
 282
 283   A -> B -> SUCCESS
 284     - commit state
 285
 286   A -> B -> ASYNC not final state
 287     - commit state on behalf of element, continue state change
 288
 289   A -> B => ASYNC final state
 290     - no commit state
 291     - listen for commit messages on bus
 292     - for each commit message, poll elements
 293     - if no ASYNC elements, commit state
 294
 295
 296 Locking overview (element)
 297 --------------------------
 298
 299 * Element commiting SUCCESS
 300
 301  - STATE_LOCK is taken in set_state
 302  - change state is called if SUCCESS, commit state is called
 303  - commit state calls change_state to next state change.
 304  - if final state is reached, stack unwinds and result is returned to
 305    set_state and caller.
 306
 307
 308  set_state(element)       change_state (element)   commit_state
 309
 310       |                         |                       |
 311       |                         |                       |
 312   STATE_LOCK                    |                       |
 313       |                         |                       |
 314       |------------------------>|                       |
 315       |                         |                       |
 316       |                         |                       |
 317       |                         | (do state change)     |
 318       |                         |                       |
 319       |                         |                       |
 320       |                         | if SUCCESS            |
 321       |                         |---------------------->|
 322       |                         |                       | post message
 323       |                         |                       |
 324       |                         |<----------------------| if (!final) change_state (next)
 325       |                         |                       | else SIGNAL
 326       |                         |                       |
 327       |                         |                       |
 328       |                         |                       |
 329       |<------------------------|                       |
 330       |     SUCCESS
 331       |
 332   STATE_UNLOCK
 333       |
 334     SUCCESS
 335
 336
 337
 338 * Element commiting ASYNC
 339
 340  - STATE_LOCK is taken in set_state
 341  - change state is called and returns ASYNC
 342  - ASYNC returned to the caller.
 343  - element takes LOCK in streaming thread.
 344  - element calls commit_state in streaming thread.
 345  - commit state calls change_state to next state change.
 346
 347
 348  set_state(element)       change_state (element)     stream_thread      commit_state (element)
 349
 350       |                         |                          |                  |
 351       |                         |                          |                  |
 352   STATE_LOCK                    |                          |                  |
 353       |                         |                          |                  |
 354       |------------------------>|                          |                  |
 355       |                         |                          |                  |
 356       |                         |                          |                  |
 357       |                         | (start_task)             |                  |
 358       |                         |                          |                  |
 359       |                         |                     STREAM_LOCK             |
 360       |                         |                          |...               |
 361       |<------------------------|                          |                  |
 362       |     ASYNC                                     STREAM_UNLOCK           |
 363   STATE_UNLOCK                                             |                  |
 364       |                .....sync........               STATE_LOCK             |
 365     ASYNC                                                  |----------------->|
 366                                                            |                  |
 367                                                            |                  |---> post_message()
 368                                                            |                  |---> if (!final) change_state (next)
 369                                                            |                  |     else SIGNAL
 370                                                            |<-----------------|
 371                                                        STATE_UNLOCK
 372                                                            |
 373                                                       STREAM_LOCK
 374                                                            | ...
 375                                                       STREAM_UNLOCK
 376
 377 *********************************************
 378 *********************************************
 379
 380 set_state cannot be called from multiple threads at the same time. The STATE_LOCK
 381 prevents this.
 382
 383 state variables are protected with the LOCK.
 384
 385 calling set_state while gst_state is called should unlock the get_state with
 386 an error. The cookie will do that.
 387
 388
 389  set_state(element)
 390
 391   STATE_LOCK
 392
 393   LOCK
 394   update current, next, pending state
 395   cookie++
 396   UNLOCK
 397
 398   change_state
 399
 400   STATE_UNLOCK
 401
 402
 403
 404