| Top |  |  |  |  | 
| void | (*GstPromiseChangeFunc) () | 
| GstPromise * | gst_promise_new () | 
| GstPromise * | gst_promise_new_with_change_func () | 
| GstPromise * | gst_promise_ref () | 
| void | gst_promise_unref () | 
| GstPromiseResult | gst_promise_wait () | 
| void | gst_promise_reply () | 
| void | gst_promise_interrupt () | 
| void | gst_promise_expire () | 
| const GstStructure * | gst_promise_get_reply () | 
The GstPromise 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_promisesAs with all Future/Promise-like functionality, there is the concept of the producer of the value and the consumer of the value.
A GstPromise is created with gst_promise_new() by the consumer and passed
to the producer to avoid thread safety issues with the change callback.
A GstPromise can be replied to with a value (or an error) by the producer
with gst_promise_reply(). gst_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 GST_PROMISE_RESULT_EXPIRED
 state set by a call
to gst_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 GstBus.
A callback can also be installed at GstPromise creation for
result changes with gst_promise_new_with_change_func().
The change callback can be used to chain GstPromises's together as in the
following example.
| 1 2 3 4 5 6 7 8 9 | 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 GstPromise starts out with a GstPromiseResult of
GST_PROMISE_RESULT_PENDING and only ever transitions once
into one of the other GstPromiseResult's.
In order to support multi-threaded code, gst_promise_reply(),
gst_promise_interrupt() and gst_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 gst_promise_reply() and gst_promise_interrupt() cannot be called
after gst_promise_expire()
That gst_promise_reply() and gst_promise_interrupt()
cannot be called twice.
The change function set with gst_promise_new_with_change_func() is
called directly from either the gst_promise_reply(),
gst_promise_interrupt() or gst_promise_expire() and can be called
from an arbitrary thread.  GstPromise using APIs can restrict this to
a single thread or a subset of threads but that is entirely up to the API
that uses GstPromise.
void (*GstPromiseChangeFunc) (GstPromise *promise,gpointer user_data);
Since: 1.14
GstPromise * gst_promise_new_with_change_func (GstPromiseChangeFunc func,gpointer user_data,GDestroyNotify notify);
func
 will be called exactly once when transitioning out of
GST_PROMISE_RESULT_PENDING into any of the other GstPromiseResult
states.
| func | a GstPromiseChangeFunc to call. | [scope notified] | 
| user_data | argument to call  | [closure] | 
| notify | notification function that  | 
Since: 1.14
GstPromise *
gst_promise_ref (GstPromise *promise);
Increases the refcount of the given promise
 by one.
Since: 1.14
void
gst_promise_unref (GstPromise *promise);
Decreases the refcount of the promise. If the refcount reaches 0, the promise will be freed.
Since: 1.14
GstPromiseResult
gst_promise_wait (GstPromise *promise);
Wait for promise
 to move out of the GST_PROMISE_RESULT_PENDING state.
If promise
 is not in GST_PROMISE_RESULT_PENDING then it will return
immediately with the current result.
Since: 1.14
void gst_promise_reply (GstPromise *promise,GstStructure *s);
Set a reply on promise
.  This will wake up any waiters with
GST_PROMISE_RESULT_REPLIED.  Called by the producer of the value to
indicate success (or failure).
If promise
 has already been interrupted by the consumer, then this reply
is not visible to the consumer.
| promise | a GstPromise. | [allow-none] | 
| s | a GstStructure with the the reply contents. | [transfer full] | 
Since: 1.14
void
gst_promise_interrupt (GstPromise *promise);
Interrupt waiting for a promise
.  This will wake up any waiters with
GST_PROMISE_RESULT_INTERRUPTED.  Called when the consumer does not want
the value produced anymore.
Since: 1.14
void
gst_promise_expire (GstPromise *promise);
Expire a promise
.  This will wake up any waiters with
GST_PROMISE_RESULT_EXPIRED.  Called by a message loop when the parent
message is handled and/or destroyed (possibly unanswered).
Since: 1.14
const GstStructure *
gst_promise_get_reply (GstPromise *promise);
Retrieve the reply set on promise
.  promise
 must be in
GST_PROMISE_RESULT_REPLIED and the returned structure is owned by promise
Since: 1.14
The result of a GstPromise
| Initial state. Waiting for transition to any other state. | ||
| Interrupted by the consumer as it doesn't want the value anymore. | ||
| A producer marked a reply | ||
| The promise expired (the carrying object lost all refs) and the promise will never be fulfilled. | 
Since: 1.14