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