Enum TransitionStatus 

pub enum TransitionStatus {
    Ready(Result<TransitionOk, TransitionError>),
    Pending {
        trigger: Trigger,
        origin: TaskState,
        res_fut: Pin<Box<dyn Future<Output = Result<TransitionOk, TransitionError>> + Send>>,
    },
}

Transition status.

A state transition occurs as a result of a triggering event. The triggering event is asynchronously handled by a state machine running on a Context.

Variants

Ready(Result<TransitionOk, TransitionError>)

Transition result is ready.

Pending

Transition is pending.

Fields

trigger: Trigger

origin: TaskState

res_fut: Pin<Box<dyn Future<Output = Result<TransitionOk, TransitionError>> + Send>>

Implementations

impl TransitionStatus

pub fn is_ready(&self) -> bool

pub fn is_pending(&self) -> bool

pub fn check(self) -> Result<TransitionStatus, TransitionError>

Converts the TransitionStatus into a Result.

This function allows getting the TransitionError when the transition result is ready without awaiting nor blocking.

See also [Self::await_maybe_on_context].

pub fn block_on_or_add_subtask<O>( self, obj: &O, ) -> Result<TransitionOk, TransitionError>

where O: IsA<Object> + Send,

Blocks on this state transition to complete, or adds a subtask if running on a Context.

Notes:

• If you need to execute code after the transition succeeds or fails, see [block_on_or_add_subtask_then].
• When running in an async block within a running transition or task iteration, don’t await for the transition as it would deadlock. Use Self::check to make sure the state transition is valid.
• When running in an async block out of a running transition or task iteration, just .await normally. E.g.:

  let flush_ok = task.flush_start().await?;

This function makes sure the transition completes successfully or produces an error. It must be used in situations where we don’t know whether we are running on a Context or not. This is the case for functions in PadSrc and PadSink as well as the synchronous functions transitively called from them.

As an example, a PadSrc::src_event function which handles a FlushStart could call:

  return task
      .flush_start()
      .block_on_or_add_subtask()
      .is_ok();

If the transition is already complete, the result is returned immediately.

If we are NOT running on a Context, the transition result is awaited by blocking on current thread and the result is returned.

If we are running on a Context, the transition result is awaited in a sub task for current Context’s Scheduler task. As a consequence, the sub task will be awaited in usual Context::drain_sub_tasks rendezvous, ensuring some kind of synchronization. To avoid deadlocks, Ok(TransitionOk::NotWaiting { .. }) is immediately returned.

pub fn block_on_or_add_subtask_then<T, F>( self, obj: BorrowedObject<'_, T>, func: F, ) -> Result<(), ErrorMessage>

where T: IsA<Object> + Send, F: FnOnce(&T, &Result<TransitionOk, TransitionError>) + Send + 'static,

Blocks on this state transition to complete, or adds a subtask if running on a Context executing the provided function after the transition succeeds or fails.

Compared to [block_on_or_addsubtask], this function also executes the provieded func after the transition succeeded or failed. Code following [block_on_or_addsubtask] can actually be executed before the transition if a subtask was added and the returned Result might not reflect the actual transition result.

If the transition is already complete, func is executed immediately.

If we are NOT running on a Context, the transition result is awaited by blocking on current thread and func is executed.

If we are running on a Context, the transition result is awaited in a sub task for current Context’s Scheduler task and func is executed with the transition result. In this case, block_on_or_add_subtask_then always returns Ok(()) since the actual processing is handled asynchronously.

Example

  task
      .stop()
      .block_on_or_add_subtask_then(self.obj(), |elem, res| {
          // Add specific stop code here,
          // it will be executed after the transition succeeds or fails

          if res.is_ok() {
              gst::debug!(CAT, obj = elem, "Stopped");
          }
      })

Trait Implementations

impl Debug for TransitionStatus

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<TransitionError> for TransitionStatus

fn from(err: TransitionError) -> Self

Converts to this type from the input type.

impl From<TransitionOk> for TransitionStatus

fn from(ok: TransitionOk) -> Self

Converts to this type from the input type.

impl Future for TransitionStatus

type Output = Result<TransitionOk, TransitionError>

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Attempts to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.