Struct gstreamer::promise::Promise

pub struct Promise(_);

This is supported on crate feature v1_14 only.

The crate::Promise object implements the container for values that may be available later. i.e. a Future or a Promise in https://en.wikipedia.org/wiki/Futures_and_promises. As with all Future/Promise-like functionality, there is the concept of the producer of the value and the consumer of the value.

A crate::Promise is created with Self::new() by the consumer and passed to the producer to avoid thread safety issues with the change callback. A crate::Promise can be replied to with a value (or an error) by the producer with Self::reply(). The exact value returned is defined by the API contract of the producer and None may be a valid reply. Self::interrupt() is for the consumer to indicate to the producer that the value is not needed anymore and producing that value can stop. The crate::PromiseResult::Expired (XXX: @-reference does not belong to Promise!) state set by a call to Self::expire() indicates to the consumer that a value will never be produced and is intended to be called by a third party that implements some notion of message handling such as crate::Bus. A callback can also be installed at crate::Promise creation for result changes with [Self::new_with_change_func()]. The change callback can be used to chain GstPromises’s together as in the following example.

const GstStructure *reply;
GstPromise *p;
if (gst_promise_wait (promise) != GST_PROMISE_RESULT_REPLIED)
  return; // interrupted or expired value
reply = gst_promise_get_reply (promise);
if (error in reply)
  return; // propagate error
p = gst_promise_new_with_change_func (another_promise_change_func, user_data, notify);
pass p to promise-using API

Each crate::Promise starts out with a crate::PromiseResult of crate::PromiseResult::Pending and only ever transitions once into one of the other crate::PromiseResult’s.

In order to support multi-threaded code, Self::reply(), Self::interrupt() and Self::expire() may all be from different threads with some restrictions and the final result of the promise is whichever call is made first. There are two restrictions on ordering:

1. That Self::reply() and Self::interrupt() cannot be called after Self::expire()
2. That Self::reply() and Self::interrupt() cannot be called twice.

The change function set with [Self::new_with_change_func()] is called directly from either the Self::reply(), Self::interrupt() or Self::expire() and can be called from an arbitrary thread. crate::Promise using APIs can restrict this to a single thread or a subset of threads but that is entirely up to the API that uses crate::Promise.

Implementations

impl Promise

pub fn new() -> Promise

Returns

a new crate::Promise

pub fn with_change_func<F>(func: F) -> Promise where
    F: FnOnce(Result<Option<&StructureRef>, PromiseError>) + Send + 'static, 

pub fn new_future() -> (Self, PromiseFuture)

pub fn expire(&self)

Expire a self. This will wake up any waiters with crate::PromiseResult::Expired. Called by a message loop when the parent message is handled and/or destroyed (possibly unanswered).

pub fn get_reply(&self) -> Option<&StructureRef>

Retrieve the reply set on self. self must be in crate::PromiseResult::Replied and the returned structure is owned by self

Returns

The reply set on self

pub fn interrupt(&self)

Interrupt waiting for a self. This will wake up any waiters with crate::PromiseResult::Interrupted. Called when the consumer does not want the value produced anymore.

pub fn reply(&self, s: Option<Structure>)

Set a reply on self. This will wake up any waiters with crate::PromiseResult::Replied. Called by the producer of the value to indicate success (or failure).

If self has already been interrupted by the consumer, then this reply is not visible to the consumer.

s

a crate::Structure with the the reply contents

pub fn wait(&self) -> PromiseResult

Wait for self to move out of the crate::PromiseResult::Pending state. If self is not in crate::PromiseResult::Pending then it will return immediately with the current result.

Returns

the result of the promise

Trait Implementations

impl Clone for Promise

fn clone(&self) -> Promise

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Promise

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

Formats the value using the given formatter.

impl Default for Promise

fn default() -> Self

Returns the “default value” for a type.

impl Hash for Promise

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl Ord for Promise

fn cmp(&self, other: &Promise) -> Ordering

This method returns an Ordering between self and other.

#[must_use]

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl PartialEq<Promise> for Promise

fn eq(&self, other: &Promise) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Promise) -> bool

This method tests for !=.

impl PartialOrd<Promise> for Promise

fn partial_cmp(&self, other: &Promise) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for Promise

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for Promise

impl Send for Promise

impl StructuralEq for Promise

impl StructuralPartialEq for Promise

impl Sync for Promise