Promise

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_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 #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 2. 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.

class Promise : Boxed {

this();

static gst.promise.Promise newWithChangeFunc(gst.types.PromiseChangeFunc func);

void expire();

gst.structure.Structure getReply();

void interrupt();

void reply(gst.structure.Structure s);

gst.types.PromiseResult wait();

}

Constructors

this this()

Members

Functions

expire void expire(): Expire a promise. This will wake up any waiters with gst.types.PromiseResult.Expired. Called by a message loop when the parent message is handled and/or destroyed (possibly unanswered).
getReply gst.structure.Structure getReply(): Retrieve the reply set on promise. promise must be in gst.types.PromiseResult.Replied and the returned structure is owned by promise
interrupt void interrupt(): Interrupt waiting for a promise. This will wake up any waiters with gst.types.PromiseResult.Interrupted. Called when the consumer does not want the value produced anymore.
reply void reply(gst.structure.Structure s): Set a reply on promise. This will wake up any waiters with gst.types.PromiseResult.Replied. Called by the producer of the value to indicate success (or failure).
wait gst.types.PromiseResult wait(): Wait for promise to move out of the gst.types.PromiseResult.Pending state. If promise is not in gst.types.PromiseResult.Pending then it will return immediately with the current result.

Static functions

newWithChangeFunc gst.promise.Promise newWithChangeFunc(gst.types.PromiseChangeFunc func): func will be called exactly once when transitioning out of gst.types.PromiseResult.Pending into any of the other #GstPromiseResult states.

Inherited Members

From Boxed

cInstancePtr void* cInstancePtr;: Pointer to the C boxed value
getType GType getType(): Get the GType of this boxed type.
gType GType gType [@property getter]: Boxed GType property.
self Boxed self(): Convenience method to return this cast to a type. For use in D with statements.
copy_ void* copy_(): Make a copy of the wrapped C boxed data.
boxedCopy void* boxedCopy(void* cBoxed): Copy a C boxed value using g_boxed_copy.
boxedFree void boxedFree(void* cBoxed): Free a C boxed value using g_boxed_free.

gst promise classes

Promise