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
</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:
- That
Promise::reply
andPromise::interrupt
cannot be called afterPromise::expire
- That
Promise::reply
andPromise::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]
impl Promise
pub fn new() -> Promise
[src]
pub fn new() -> Promise
pub fn new_with_change_func<F>(func: F) -> Promise where
F: FnOnce(&Promise) + Send + 'static,
[src]
pub fn new_with_change_func<F>(func: F) -> Promise where
F: FnOnce(&Promise) + Send + 'static,
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]
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).
Feature: v1_14
pub fn get_reply(&self) -> Option<&StructureRef>
[src]
pub fn get_reply(&self) -> Option<&StructureRef>
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]
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.
Feature: v1_14
pub fn reply(&self, s: Structure)
[src]
pub fn reply(&self, s: Structure)
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]
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.
Feature: v1_14
Returns
the result of the promise
Trait Implementations
impl Clone for Promise
impl Clone for Promise
fn clone(&self) -> Promise
fn clone(&self) -> Promise
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0[src]
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from source
. Read more
impl StaticType for Promise
impl StaticType for Promise
fn static_type() -> Type
fn static_type() -> Type
Returns the type identifier of Self
.
impl Default for Promise
[src]
impl Default for Promise
impl Send for Promise
[src]
impl Send for Promise
impl Sync for Promise
[src]
impl Sync for Promise