| Top |  |
 |
 |
 |
Functions
| 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 () |
Description
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()andgst_promise_interrupt()cannot be called aftergst_promise_expire()That
gst_promise_reply()andgst_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.
Functions
GstPromiseChangeFunc ()
void (*GstPromiseChangeFunc) (GstPromise *promise,gpointer user_data);
Since: 1.14
gst_promise_new_with_change_func ()
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.
Parameters
func |
a GstPromiseChangeFunc to call. |
[scope notified] |
user_data |
argument to call |
[closure] |
notify |
notification function that |
Since: 1.14
gst_promise_ref ()
GstPromise *
gst_promise_ref (GstPromise *promise);
Increases the refcount of the given promise
by one.
Since: 1.14
gst_promise_unref ()
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
gst_promise_wait ()
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
gst_promise_reply ()
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.
Parameters
promise |
a GstPromise. |
[allow-none] |
s |
a GstStructure with the the reply contents. |
[transfer full] |
Since: 1.14
gst_promise_interrupt ()
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
gst_promise_expire ()
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
gst_promise_get_reply ()
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
Types and Values
enum GstPromiseResult
The result of a GstPromise
Members
|
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