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 constrain
  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 (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.
  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 allowed 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      sometimes 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 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.
  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    - Elements remove all sometimes pads
  85
  86  READY -> NULL
  87    - Elements close devices
  88    - Elements reset any internal state.
  89
  90
  91 State variables
  92 ~~~~~~~~~~~~~~~
  93
  94 An element has 4 state variables that are protected with the object LOCK:
  95
  96   - STATE
  97   - STATE_NEXT
  98   - STATE_PENDING
  99   - STATE_RETURN
 100
 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.
 105
 106 The STATE_NEXT and STATE_PENDING can be VOID_PENDING if the element is in
 107 the right state.
 108
 109 An element has a special lock to protect against concurrent invocations of
 110 _set_state(), called the STATE_LOCK.
 111
 112
 113 Setting state on elements
 114 ~~~~~~~~~~~~~~~~~~~~~~~~~
 115
 116 The state of an element can be changed with _element_set_state(). When changing
 117 the state of an element all intermediate states will also be set on the element
 118 until the final desired state is set.
 119
 120 The _set_state() function can return 3 possible values:
 121
 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.
 124
 125   GST_STATE_SUCCESS: The state change is completed successfully.
 126
 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).
 131
 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.
 134
 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().
 141
 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 immediately returned to the caller.
 147
 148
 149 Getting state of elements
 150 ~~~~~~~~~~~~~~~~~~~~~~~~~
 151
 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.
 155
 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.
 159
 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.
 163
 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
 167    of _set_state().
 168
 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.
 172
 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.
 176
 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.
 179
 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      successful 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.
 184
 185
 186 States in GstBin
 187 ~~~~~~~~~~~~~~~~
 188
 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.
 193
 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
 199 error.
 200
 201 If all the children return SUCCESS, the function returns SUCCESS as well.
 202
 203 If one of the children returns FAILURE, the function returns FAILURE as well. In
 204 this state it is possible that some elements successfully 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()
 207 on the elements.
 208
 209 If after calling the state function on all children, one of the children returned
 210 ASYNC, the function returns ASYNC as well.
 211
 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.
 214
 215 If both NO_PREROLL and ASYNC children are present, NO_PREROLL is returned.
 216
 217 The current state of the bin can be retrieved with _get_state().
 218
 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.
 221
 222
 223 Implementing states in elements
 224 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 225
 226 READY
 227 ^^^^^
 228
 229
 230
 231 upward state change
 232 ~~~~~~~~~~~~~~~~~~~
 233
 234 Upward state changes always return ASYNC either if the STATE_PENDING is
 235 reached or not.
 236
 237 Element:
 238
 239   A -> B => SUCCESS
 240     - commit state
 241
 242   A -> B => ASYNC
 243     - no commit state
 244     - element commits state ASYNC
 245
 246   A -> B while ASYNC
 247     - update STATE_PENDING state
 248     - no commit state
 249     - no change_state called on element
 250
 251 Bin:
 252
 253   A->B: all elements SUCCESS
 254     - commit state
 255
 256   A->B: some elements ASYNC
 257     - no commit state
 258     - listen for commit messages on bus
 259     - for each commit message, poll elements, this happens in another
 260       thread.
 261     - if no ASYNC elements, commit state, continue state change
 262       to STATE_PENDING
 263
 264 downward state change
 265 ~~~~~~~~~~~~~~~~~~~~~
 266
 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.
 271
 272 Element:
 273
 274   A -> B => SUCCESS
 275     - commit state
 276
 277   A -> B => ASYNC not final state
 278     - commit state on behalf of element
 279
 280   A -> B => ASYNC final state
 281     - element will commit ASYNC
 282
 283 Bin:
 284
 285   A -> B -> SUCCESS
 286     - commit state
 287
 288   A -> B -> ASYNC not final state
 289     - commit state on behalf of element, continue state change
 290
 291   A -> B => ASYNC final state
 292     - no commit state
 293     - listen for commit messages on bus
 294     - for each commit message, poll elements
 295     - if no ASYNC elements, commit state
 296
 297
 298 Locking overview (element)
 299 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 300
 301 * Element commiting SUCCESS
 302
 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.
 308
 309
 310  set_state(element)       change_state (element)   commit_state
 311
 312       |                         |                       |
 313       |                         |                       |
 314   STATE_LOCK                    |                       |
 315       |                         |                       |
 316       |------------------------>|                       |
 317       |                         |                       |
 318       |                         |                       |
 319       |                         | (do state change)     |
 320       |                         |                       |
 321       |                         |                       |
 322       |                         | if SUCCESS            |
 323       |                         |---------------------->|
 324       |                         |                       | post message
 325       |                         |                       |
 326       |                         |<----------------------| if (!final) change_state (next)
 327       |                         |                       | else SIGNAL
 328       |                         |                       |
 329       |                         |                       |
 330       |                         |                       |
 331       |<------------------------|                       |
 332       |     SUCCESS
 333       |
 334   STATE_UNLOCK
 335       |
 336     SUCCESS
 337
 338
 339
 340 * Element commiting ASYNC
 341
 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.
 348
 349
 350  set_state(element)       change_state (element)     stream_thread      commit_state (element)
 351
 352       |                         |                          |                  |
 353       |                         |                          |                  |
 354   STATE_LOCK                    |                          |                  |
 355       |                         |                          |                  |
 356       |------------------------>|                          |                  |
 357       |                         |                          |                  |
 358       |                         |                          |                  |
 359       |                         | (start_task)             |                  |
 360       |                         |                          |                  |
 361       |                         |                     STREAM_LOCK             |
 362       |                         |                          |...               |
 363       |<------------------------|                          |                  |
 364       |     ASYNC                                     STREAM_UNLOCK           |
 365   STATE_UNLOCK                                             |                  |
 366       |                .....sync........               STATE_LOCK             |
 367     ASYNC                                                  |----------------->|
 368                                                            |                  |
 369                                                            |                  |---> post_message()
 370                                                            |                  |---> if (!final) change_state (next)
 371                                                            |                  |     else SIGNAL
 372                                                            |<-----------------|
 373                                                        STATE_UNLOCK
 374                                                            |
 375                                                       STREAM_LOCK
 376                                                            | ...
 377                                                       STREAM_UNLOCK
 378
 379 Remarks
 380 ~~~~~~~
 381
 382 set_state cannot be called from multiple threads at the same time. The STATE_LOCK
 383 prevents this.
 384
 385 state variables are protected with the LOCK.
 386
 387 calling set_state while gst_state is called should unlock the get_state with
 388 an error. The cookie will do that.
 389
 390
 391  set_state(element)
 392
 393   STATE_LOCK
 394
 395   LOCK
 396   update current, next, pending state
 397   cookie++
 398   UNLOCK
 399
 400   change_state
 401
 402   STATE_UNLOCK
 403
 404
 405
 406