[]Struct gstreamer::Promise

pub struct Promise(_);

The 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</ulink> As with all Future/Promise-like functionality, there is the concept of the producer of the value and the consumer of the value.

A Promise is created with Promise::new by the consumer and passed to the producer to avoid thread safety issues with the change callback. A Promise can be replied to with a value (or an error) by the producer with Promise::reply. Promise::interrupt is for the consumer to indicate to the producer that the value is not needed anymore and producing that value can stop. The PromiseResult::Expired state set by a call to Promise::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 Bus. A callback can also be installed at Promise creation for result changes with Promise::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 Promise starts out with a PromiseResult of PromiseResult::Pending and only ever transitions once into one of the other PromiseResult's.

In order to support multi-threaded code, Promise::reply, Promise::interrupt and Promise::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 Promise::reply and Promise::interrupt cannot be called after Promise::expire
  2. That Promise::reply and Promise::interrupt cannot be called twice.

The change function set with Promise::new_with_change_func is called directly from either the Promise::reply, Promise::interrupt or Promise::expire and can be called from an arbitrary thread. 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 Promise.

Feature: v1_14

Methods

impl Promise[src]

pub fn new() -> Promise[src]

Feature: v1_14

Returns

a new Promise

pub fn new_with_change_func<F>(func: F) -> Promise where
    F: FnOnce(&Promise) + Send + 'static, 
[src]

func will be called exactly once when transitioning out of PromiseResult::Pending into any of the other PromiseResult states.

Feature: v1_14

func

a GstPromiseChangeFunc to call

user_data

argument to call func with

notify

notification function that user_data is no longer needed

Returns

a new Promise

pub fn expire(&self)[src]

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

Feature: v1_14

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

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

Feature: v1_14

Returns

The reply set on self

pub fn interrupt(&self)[src]

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

Feature: v1_14

pub fn reply(&self, s: Structure)[src]

Set a reply on self. This will wake up any waiters with 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.

Feature: v1_14

s

a Structure with the the reply contents

pub fn wait(&self) -> PromiseResult[src]

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

Feature: v1_14

Returns

the result of the promise

Trait Implementations

impl Clone for Promise

fn clone_from(&mut self, source: &Self)1.0.0[src]

Performs copy-assignment from source. Read more

impl Eq for Promise[src]

impl Ord for Promise[src]

fn max(self, other: Self) -> Self1.21.0[src]

Compares and returns the maximum of two values. Read more

fn min(self, other: Self) -> Self1.21.0[src]

Compares and returns the minimum of two values. Read more

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

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval. Read more

impl Default for Promise[src]

impl Sync for Promise[src]

impl Send for Promise[src]

impl PartialEq<Promise> for Promise[src]

impl PartialOrd<Promise> for Promise[src]

impl Debug for Promise[src]

impl Hash for Promise[src]

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

Feeds a slice of this type into the given [Hasher]. Read more

impl StaticType for Promise

Blanket Implementations

impl<T> From<T> for T[src]

impl<T> ToOwned for T where
    T: Clone
[src]

type Owned = T

The resulting type after obtaining ownership.

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<'a, T> ToGlibContainerFromSlice<'a, *mut GList> for T where
    T: GlibPtrDefault + ToGlibPtr<'a, <T as GlibPtrDefault>::GlibType>, 
[src]

impl<'a, T> ToGlibContainerFromSlice<'a, *mut GArray> for T where
    T: GlibPtrDefault + ToGlibPtr<'a, <T as GlibPtrDefault>::GlibType>, 
[src]

impl<'a, T> ToGlibContainerFromSlice<'a, *const GList> for T where
    T: GlibPtrDefault + ToGlibPtr<'a, <T as GlibPtrDefault>::GlibType>, 
[src]

impl<T> ToValue for T where
    T: SetValue + ?Sized
[src]

impl<T> ToSendValue for T where
    T: ToValue + SetValue + Send + ?Sized
[src]