gst.promise

The #GstPromise object implements the container for values that may be available later. i.e. a Future or a Promise in

As 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.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.Promise.reply]. The exact value returned is defined by the API contract of the producer and null may be a valid reply. [gst.promise.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.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.Promise.newWithChangeFunc]. 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 #GstPromise starts out with a #GstPromiseResult of [gst.types.PromiseResult.Pending] and only ever transitions once into one of the other #GstPromiseResult's.

In order to support multi-threaded code, [gst.promise.Promise.reply], [gst.promise.Promise.interrupt] and [gst.promise.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 [gst.promise.Promise.reply] and [gst.promise.Promise.interrupt] cannot be called

after [gst.promise.Promise.expire]

1. That [gst.promise.Promise.reply] and [gst.promise.Promise.interrupt]

cannot be called twice.

The change function set with [gst.promise.Promise.newWithChangeFunc] is called directly from either the [gst.promise.Promise.reply], [gst.promise.Promise.interrupt] or [gst.promise.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.