Promise

The gstreamer.Promise object implements the container for values that may be available later. i.e. a Future or a Promise in <ulink url="https://en.wikipedia.org/wiki/Futures_and_promises">https://en.wikipedia.org/wiki/Futures_and_promises</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 gstreamer.Promise is created with Promise.new by the consumer and passed to the producer to avoid thread safety issues with the change callback. A gstreamer.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 GST_PROMISE_RESULT_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 gstreamer.Bus A callback can also be installed at gstreamer.Promise creation for result changes with Promise.newWithChangeFunc. The change callback can be used to chain gstreamer.Promises'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 gstreamer.Promise 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, 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:

1. That Promise.reply and Promise.interrupt cannot be called after Promise.expire 2. That Promise.reply and Promise.interrupt cannot be called twice.

The change function set with Promise.newWithChangeFunc is called directly from either the Promise.reply, Promise.interrupt or Promise.expire and can be called from an arbitrary thread. gstreamer.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 gstreamer.Promise

class Promise {

protected

GstPromise* gstPromise;

protected

bool ownedRef;

GstPromise* getPromiseStruct(bool transferOwnership);

void* getStruct();

this(GstPromise* gstPromise, bool ownedRef);

static GType getType();

this();

this(GstPromiseChangeFunc func, void* userData, GDestroyNotify notify);

void expire();

Structure getReply();

void interrupt();

void reply(Structure s);

GstPromiseResult wait();

}

Constructors

this this(GstPromise* gstPromise, bool ownedRef): Sets our main struct and passes it to the parent class.
this this()
this this(GstPromiseChangeFunc func, void* userData, GDestroyNotify notify): func will be called exactly once when transitioning out of GST_PROMISE_RESULT_PENDING into any of the other GstPromiseResult states.

Members

Functions

expire void expire(): 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).
getPromiseStruct GstPromise* getPromiseStruct(bool transferOwnership): Get the main Gtk struct
getReply Structure getReply(): Retrieve the reply set on promise. promise must be in GST_PROMISE_RESULT_REPLIED and the returned structure is owned by promise
getStruct void* getStruct(): the main Gtk struct as a void*
interrupt void interrupt(): 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.
reply void reply(Structure 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).
wait GstPromiseResult wait(): 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.

Static functions

getType GType getType()

Variables

gstPromise GstPromise* gstPromise;: the main Gtk struct