Struct gstreamer::promise::Promise

pub struct Promise { /* private fields */ }

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. 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 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 reply(). The exact value returned is defined by the API contract of the producer and None may be a valid reply. 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 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 with_change_func(). The change callback can be used to chain GstPromises’s together as in the following example.

⚠️ The following code is in C ⚠️

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, reply(), interrupt() and 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 reply() and interrupt() cannot be called after expire()
2. That reply() and interrupt() cannot be called twice.

The change function set with with_change_func() is called directly from either the reply(), interrupt() or 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.

GLib type: Shared boxed type with reference counted clone semantics.

Implementations

impl Promise

pub fn as_ptr(&self) -> *mut GstPromise

Return the inner pointer to the underlying C value.

pub unsafe fn from_glib_ptr_borrow(ptr: &*mut GstPromise) -> &Self

Borrows the underlying C value.

impl Promise

pub fn new() -> Promise

Returns

a new Promise

pub fn with_change_func<F>(func: F) -> Promise

where F: FnOnce(Result<Option<&StructureRef>, PromiseError>) + Send + 'static,

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

func

a GstPromiseChangeFunc to call

notify

notification function that user_data is no longer needed

Returns

a new Promise

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

pub fn expire(&self)

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).

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

pub fn interrupt(&self)

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.

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

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

Returns

The reply set on self

pub fn wait(&self) -> PromiseResult

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.

Returns

the result of the promise

Trait Implementations

impl Clone for Promise

fn clone(&self) -> Self

Makes a clone of this shared reference.

This increments the strong reference count of the reference. Dropping the reference will decrement it again.

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 From<Promise> for Value

fn from(s: Promise) -> Self

Converts to this type from the input type.

impl HasParamSpec for Promise

type ParamSpec = ParamSpecBoxed

type SetValue = Promise

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(_: &str) -> ParamSpecBoxedBuilder<'_, Promise>

fn param_spec_builder() -> Self::BuilderFn

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, Self: Sized,

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.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

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

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for Promise

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Promise

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

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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 StructuralPartialEq for Promise

impl Sync for Promise