mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-12-25 01:30:38 +00:00
Code Issues 1 Projects Releases Wiki Activity

design: states: section breakdown, markup, readability and grammar fixes

Browse source
This commit is contained in:
Reynaldo H. Verdejo Pinochet 2016-12-29 23:51:39 -08:00
parent 5d7f7c112c
commit 3e315b6b2e
1 changed files with 97 additions and 101 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

198
markdown/design/states.md
View file

@ -4,84 +4,84 @@ Both elements and pads can be in different states. The states of the
pads are linked to the state of the element so the design of the states pads are linked to the state of the element so the design of the states
is mainly focused around the element states. is mainly focused around the element states.
An element can be in 4 states. NULL, READY, PAUSED and PLAYING. When an An element can be in 4 states. `NULL`, `READY`, `PAUSED` and `PLAYING`. When an
element is initially instantiated, it is in the NULL state. element is initially instantiated, it is in the NULL state.
## State definitions ## State definitions
- NULL: This is the initial state of an element. - `NULL`: This is the initial state of an element.
- READY: The element should be prepared to go to PAUSED. - `READY`: The element should be prepared to go to PAUSED.
- PAUSED: The element should be ready to accept and process data. Sink - `PAUSED`: The element should be ready to accept and process data. Sink
elements however only accept one buffer and then block. elements, however, only accept one buffer and then block.
- PLAYING: The same as PAUSED except for live sources and sinks. Sinks - `PLAYING`: The same as PAUSED except for live sources and sinks. Sinks
accept and render data. Live sources produce data. accept and render data. Live sources produce data.
We call the sequence NULL→PLAYING an upwards state change and We call the sequence `NULL→PLAYING` an upwards state change and
PLAYING→NULL a downwards state change. `PLAYING→NULL` a downwards state change.
## State transitions ## State transitions
the following state changes are possible: the following state changes are possible:
* *NULL -> READY*: * `NULL -> READY`:
- The element must check if the resources it needs are available. - The element must check if the resources it needs are available.
Device sinks and sources typically try to probe the device to constrain Device sinks and sources typically try to probe the device to constrain
their caps. their caps.
- The element opens the device, this is needed if the previous step requires - The element opens the device, this is needed if the previous step requires
the device to be opened. the device to be opened.
* *READY -> PAUSED*: * `READY -> PAUSED`:
- The element pads are activated in order to receive data in PAUSED. - The element pads are activated in order to receive data in `PAUSED`.
Streaming threads are started. Streaming threads are started.
- Some elements might need to return `ASYNC` and complete the state change - Some elements might need to return `ASYNC` and complete the state change
when they have enough information. It is a requirement for sinks to when they have enough information. It is a requirement for sinks to
return `ASYNC` and complete the state change when they receive the first return `ASYNC` and complete the state change when they receive the first
buffer or EOS event (preroll). Sinks also block the dataflow when in PAUSED. buffer or EOS event (preroll). Sinks also block the dataflow when in PAUSED.
- A pipeline resets the running_time to 0. - A pipeline resets the `running_time` to 0.
- Live sources return NO_PREROLL and don't generate data. - Live sources return `NO_PREROLL` and don't generate data.
* *PAUSED -> PLAYING*: * `PAUSED -> PLAYING`:
- Most elements ignore this state change. - Most elements ignore this state change.
- The pipeline selects a clock and distributes this to all the children - The pipeline selects a clock and distributes this to all the children
before setting them to PLAYING. This means that it is only allowed to before setting them to `PLAYING`. This means that it is only allowed to
synchronize on the clock in the PLAYING state. synchronize on the clock in the `PLAYING` state.
- The pipeline uses the clock and the running_time to calculate the base_time. - The pipeline uses the clock and the `running_time` to calculate the
The base_time is distributed to all children when performing the state `base_time`. This `base_time` is distributed to all children when
change. performing the state change.
- Sink elements stop blocking on the preroll buffer or event and start - Sink elements stop blocking on the preroll buffer or event and start
rendering the data. rendering the data.
- Sinks can post the EOS message in the PLAYING state. It is not allowed to - Sinks can post the EOS message in the `PLAYING` state. It is not allowed to
post EOS when not in the PLAYING state. post EOS when not in the `PLAYING` state.
- While streaming in PAUSED or PLAYING elements can create and remove - While streaming in `PAUSED` or `PLAYING` elements can create and remove
sometimes pads. sometimes pads.
- Live sources start generating data and return SUCCESS. - Live sources start generating data and return `SUCCESS`.
* *PLAYING -> PAUSED*: * `PLAYING -> PAUSED`:
- Most elements ignore this state change. - Most elements ignore this state change.
- The pipeline calculates the running_time based on the last selected clock - The pipeline calculates the `running_time` based on the last selected clock
and the base_time. It stores this information to continue playback when and the `base_time`. It stores this information to continue playback when
going back to the PLAYING state. going back to the `PLAYING` state.
- Sinks unblock any clock wait calls. - Sinks unblock any clock wait calls.
- When a sink does not have a pending buffer to play, it returns `ASYNC` from - When a sink does not have a pending buffer to play, it returns `ASYNC` from
this state change and completes the state change when it receives a new this state change and completes the state change when it receives a new
buffer or an EOS event. buffer or an EOS event.
- Any queued EOS messages are removed since they will be reposted when going - Any queued EOS messages are removed since they will be reposted when going
back to the PLAYING state. The EOS messages are queued in GstBins. back to the PLAYING state. The EOS messages are queued in `GstBins`.
- Live sources stop generating data and return NO_PREROLL. - Live sources stop generating data and return `NO_PREROLL`.
* *PAUSED -> READY*: * `PAUSED -> READY`:
- Sinks unblock any waits in the preroll. - Sinks unblock any waits in the preroll.
- Elements unblock any waits on devices - Elements unblock any waits on devices
- Chain or get_range functions return FLUSHING. - Chain or `get_range()` functions return `FLUSHING`.
- The element pads are deactivated so that streaming becomes impossible and - The element pads are deactivated so that streaming becomes impossible and
all streaming threads are stopped. all streaming threads are stopped.
- The sink forgets all negotiated formats - The sink forgets all negotiated formats
- Elements remove all sometimes pads - Elements remove all sometimes pads
* *READY -> NULL*: * `READY -> NULL`:
- Elements close devices - Elements close devices
- Elements reset any internal state. - Elements reset any internal state.
@ -89,82 +89,81 @@ the following state changes are possible:
An element has 4 state variables that are protected with the object LOCK: An element has 4 state variables that are protected with the object LOCK:
- *STATE* - `STATE`
- *STATE_NEXT* - `STATE_NEXT`
- *STATE_PENDING* - `STATE_PENDING`
- *STATE_RETURN* - `STATE_RETURN`
The STATE always reflects the current state of the element. The The `STATE` always reflects the current state of the element. The
STATE\_NEXT reflects the next state the element will go to. The `STATE_NEXT` reflects the next state the element will go to. The
STATE\_PENDING always reflects the required state of the element. The `STATE_PENDING` always reflects the required state of the element. The
STATE\_RETURN reflects the last return value of a state change. `STATE_RETURN` reflects the last return value of a state change.
The STATE\_NEXT and STATE\_PENDING can be VOID\_PENDING if the element The `STATE_NEXT` and `STATE_PENDING` can be `VOID_PENDING` if the element
is in the right state. is in the right state.
An element has a special lock to protect against concurrent invocations An element has a special lock to protect against concurrent invocations
of set\_state(), called the STATE\_LOCK. of `set_state()`, called the `STATE_LOCK`.
## Setting state on elements ## Setting state on elements
The state of an element can be changed with \_element\_set\_state(). The state of an element can be changed with `_element_set_state()`.
When changing the state of an element all intermediate states will also When changing the state of an element all intermediate states will also
be set on the element until the final desired state is set. be set on the element until the final desired state is set.
The `set\_state()` function can return 3 possible values: The `set_state()` function can return 3 possible values:
* *GST_STATE_FAILURE*: The state change failed for some reason. The plugin should * `GST_STATE_FAILURE`: The state change failed for some reason. The plugin should have posted an error message on the bus with information.
have posted an error message on the bus with information.
* *GST_STATE_SUCCESS*: The state change is completed successfully. * `GST_STATE_SUCCESS`: The state change is completed successfully.
* *GST_STATE_ASYNC*: The state change will complete later on. This can happen * `GST_STATE_ASYNC`: The state change will complete later on. This can happen
when the element needs a long time to perform the state change or for sinks when the element needs a long time to perform the state change or for sinks
that need to receive the first buffer before they can complete the state change that need to receive the first buffer before they can complete the state change
(preroll). (preroll).
* *GST_STATE_NO_PREROLL*: The state change is completed successfully but the * `GST_STATE_NO_PREROLL`: The state change is completed successfully but the
element will not be able to produce data in the PAUSED state. element will not be able to produce data in the `PAUSED` state.
In the case of an `ASYNC` state change, it is possible to proceed to the In the case of an `ASYNC` state change, it is possible to proceed to the
next state before the current state change completed, however, the next state before the current state change completes, however, the
element will only get to this next state before completing the previous element will only get to this next state before completing the previous
`ASYNC` state change. After receiving an `ASYNC` return value, you can use `ASYNC` state change. After receiving an `ASYNC` return value, you can use
`element\_get\_state()` to poll the status of the element. If the `element_get_state()` to poll the status of the element. If the
polling returns `SUCCESS`, the element completed the state change to the polling returns `SUCCESS`, the element completed the state change to the
last requested state with `set\_state()`. last requested state with `set_state()`.
When setting the state of an element, the STATE\_PENDING is set to the When setting the state of an element, the `STATE_PENDING` is set to the
required state. Then the state change function of the element is called required state. Then the state change function of the element is called
and the result of that function is used to update the STATE and and the result of that function is used to update the `STATE` and
STATE\_RETURN fields, STATE\_NEXT, STATE\_PENDING and STATE\_RETURN `STATE_RETURN` fields, `STATE_NEXT`, `STATE_PENDING` and `STATE_RETURN`
fields. If the function returned `ASYNC`, this result is immediately fields. If the function returned `ASYNC`, this result is immediately
returned to the caller. returned to the caller.
## Getting state of elements ## Getting the state of elements
The get\_state() function takes 3 arguments, two pointers that will The `get_state()` function takes 3 arguments, two pointers that will
hold the current and pending state and one GstClockTime that holds a hold the current and pending state and one `GstClockTime` that holds a
timeout value. The function returns a GstElementStateReturn. timeout value. The function returns a `GstElementStateReturn`.
- If the element returned `SUCCESS` to the previous \_set\_state() - If the element returned `SUCCESS` to the previous `_set_state()`
function, this function will return the last state set on the function, this function will return the last state set on the
element and VOID\_PENDING in the pending state value. The function element and `VOID_PENDING` in the pending state value. The function
returns GST\_STATE\_SUCCESS. returns `GST_STATE_SUCCESS`.
- If the element returned NO\_PREROLL to the previous \_set\_state() - If the element returned `NO_PREROLL` to the previous `_set_state()`
function, this function will return the last state set on the function, this function will return the last state set on the
element and VOID\_PENDING in the pending state value. The function element and `VOID_PENDING` in the pending state value. The function
returns GST\_STATE\_NO\_PREROLL. returns `GST_STATE_NO_PREROLL`.
- If the element returned FAILURE to the previous \_set\_state() call, - If the element returned `FAILURE` to the previous `_set_state()` call,
this function will return FAILURE with the state set to the current this function will return `FAILURE` with the state set to the current
state of the element and the pending state set to the value used in state of the element and the pending state set to the value used in
the last call of \_set\_state(). the last call of `_set_state()`.
- If the element returned `ASYNC` to the previous \_set\_state() call, - If the element returned `ASYNC` to the previous `_set_state()` call,
this function will wait for the element to complete its state change this function will wait for the element to complete its state change
up to the amount of time specified in the GstClockTime. up to the amount of time specified in the `GstClockTime`.
- If the element does not complete the state change in the - If the element does not complete the state change in the
specified amount of time, this function will return `ASYNC` with specified amount of time, this function will return `ASYNC` with
@ -173,19 +172,19 @@ timeout value. The function returns a GstElementStateReturn.
- If the element completes the state change within the specified - If the element completes the state change within the specified
timeout, this function returns the updated state and timeout, this function returns the updated state and
VOID\_PENDING as the pending state. `VOID_PENDING` as the pending state.
- If the element aborts the `ASYNC` state change due to an error - If the element aborts the `ASYNC` state change due to an error
within the specified timeout, this function returns FAILURE with within the specified timeout, this function returns `FAILURE` with
the state set to last successful state and pending set to the the state set to last successful state and pending set to the
last attempt. The element should also post an error message on last attempt. The element should also post an error message on
the bus with more information about the problem. the bus with more information about the problem.
## States in GstBin ## States in GstBin
A GstBin manages the state of its children. It does this by propagating A `GstBin` manages the state of its children. It does this by propagating
the state changes performed on it to all of its children. The the state changes performed on it to all of its children. The
\_set\_state() function on a bin will call the \_set\_state() function `_set_state()` function on a bin will call the `_set_state()` function
on all of its children, that are not already in the target state or in a on all of its children, that are not already in the target state or in a
change state to the target state. change state to the target state.
@ -194,27 +193,27 @@ This makes sure that when changing the state of an element, the
downstream elements are in the correct state to process the eventual downstream elements are in the correct state to process the eventual
buffers. In the case of a downwards state change, the sink elements will buffers. In the case of a downwards state change, the sink elements will
shut down first which makes the upstream elements shut down as well shut down first which makes the upstream elements shut down as well
since the \_push() function returns a GST\_FLOW\_FLUSHING error. since the `_push()` function returns a `GST_FLOW_FLUSHING` error.
If all the children return `SUCCESS`, the function returns `SUCCESS` as If all the children return `SUCCESS`, the function returns `SUCCESS` as
well. well.
If one of the children returns FAILURE, the function returns FAILURE as If one of the children returns `FAILURE`, the function returns `FAILURE` as
well. In this state it is possible that some elements successfully well. In this state it is possible that some elements successfully
changed state. The application can check which elements have a changed changed state. The application can check which elements have a changed
state, which were in error and which were not affected by iterating the state, which were in error and which were not affected by iterating the
elements and calling \_get\_state() on the elements. elements and calling `_get_state()` on the elements.
If after calling the state function on all children, one of the children If after calling the state function on all children, one of the children
returned `ASYNC`, the function returns `ASYNC` as well. returned `ASYNC`, the function returns `ASYNC` as well.
If after calling the state function on all children, one of the children If after calling the state function on all children, one of the children
returned NO\_PREROLL, the function returns NO\_PREROLL as well. returned `NO_PREROLL`, the function returns `NO_PREROLL` as well.
If both NO\_PREROLL and `ASYNC` children are present, NO\_PREROLL is If both `NO_PREROLL` and `ASYNC` children are present, `NO_PREROLL` is
returned. returned.
The current state of the bin can be retrieved with \_get\_state(). The current state of the bin can be retrieved with `_get_state()`.
If the bin is performing an `ASYNC` state change, it will automatically If the bin is performing an `ASYNC` state change, it will automatically
update its current state fields when it receives state messages from the update its current state fields when it receives state messages from the
@ -222,11 +221,9 @@ children.
## Implementing states in elements ## Implementing states in elements
### READY ### Upward state change
## upward state change Upward state changes always return `ASYNC` either if the `STATE_PENDING` is
Upward state changes always return `ASYNC` either if the STATE\_PENDING is
reached or not. reached or not.
Element: Element:
@ -239,9 +236,9 @@ Element:
- element commits state `ASYNC` - element commits state `ASYNC`
* A -> B while `ASYNC` * A -> B while `ASYNC`
- update STATE_PENDING state - update `STATE_PENDING` state
- no commit state - no commit state
- no change_state called on element - no `change_state()` called on element
Bin: Bin:
@ -254,11 +251,11 @@ Bin:
- for each commit message, poll elements, this happens in another - for each commit message, poll elements, this happens in another
thread. thread.
- if no `ASYNC` elements, commit state, continue state change - if no `ASYNC` elements, commit state, continue state change
to STATE_PENDING to `STATE_PENDING`
## downward state change ### Downward state change
Downward state changes only return `ASYNC` if the final state is ASYNC. Downward state changes only return `ASYNC` if the final state is `ASYNC`.
This is to make sure that it’s not needed to wait for an element to This is to make sure that it’s not needed to wait for an element to
complete the preroll or other `ASYNC` state changes when one only wants to complete the preroll or other `ASYNC` state changes when one only wants to
shut down an element. shut down an element.
@ -292,15 +289,14 @@ A -> B => `ASYNC` final state
- Element committing `SUCCESS` - Element committing `SUCCESS`
- STATE\_LOCK is taken in set\_state - `STATE_LOCK` is taken in `set_state()`
- change state is called if `SUCCESS`, commit state is called - change state is called if `SUCCESS`, commit state is called
- commit state calls change\_state to next state change. - commit state calls `change_state()` to next state change.
- if final state is reached, stack unwinds and result is returned - if final state is reached, stack unwinds and result is returned
to set\_state and to `set_state()` and caller.
caller.
``` ```
set_state(element) change_state (element) commit_state set_state(element) change_state (element) commit_state
@ -334,7 +330,7 @@ STATE_UNLOCK
- Element committing `ASYNC` - Element committing `ASYNC`
- STATE\_LOCK is taken in set\_state - `STATE_LOCK` is taken in `set_state()`
- change state is called and returns `ASYNC` - change state is called and returns `ASYNC`
@ -342,9 +338,9 @@ STATE_UNLOCK
- element takes LOCK in streaming thread. - element takes LOCK in streaming thread.
- element calls commit\_state in streaming thread. - element calls `commit_state` in streaming thread.
- commit state calls change\_state to next state - commit state calls `change_state()` to next state
change. change.
``` ```
@ -380,13 +376,13 @@ STATE_UNLOCK | |
## Remarks ## Remarks
set\_state cannot be called from multiple threads at the same time. The `set_state()` cannot be called from multiple threads at the same time. The
STATE\_LOCK prevents this. `STATE_LOCK` prevents this.
State variables are protected with the LOCK. State variables are protected with the LOCK.
Calling set\_state while gst\_state is called should unlock the Calling `set_state()` while `get_state()` is called should unlock the
get\_state with an error. The cookie will do that. `get_state()` with an error. The cookie will do that.
``` c ``` c
set_state(element) set_state(element)