Promise

Added in version 1.14.

class Promise(**kwargs)

The Promise 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 Promise is created with new() by the consumer and passed to the producer to avoid thread safety issues with the change callback. A Promise can be replied to with a value (or an error) by the producer with reply(). The exact value returned is defined by the API contract of the producer and None may be a valid reply. 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 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 Bus. A callback can also be installed at Promise creation for result changes with new_with_change_func(). The change callback can be used to chain Promise’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 Promise starts out with a PromiseResult of PENDING and only ever transitions once into one of the other PromiseResult’s.

In order to support multi-threaded code, reply(), interrupt() and 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 reply() and interrupt() cannot be called after expire() 2. That reply() and interrupt() cannot be called twice.

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

Constructors

class Promise

classmethod new() → Promise: Added in version 1.14.

classmethod new_with_change_func(func: Callable[[...], None], *user_data: Any) → Promise

func will be called exactly once when transitioning out of PENDING into any of the other PromiseResult states.

Added in version 1.14.

Parameters:

func – a PromiseChangeFunc to call
user_data – argument to call func with

Methods

class Promise

expire() → None: Expire a promise. This will wake up any waiters with EXPIRED. Called by a message loop when the parent message is handled and/or destroyed (possibly unanswered).

Added in version 1.14.

get_reply() → Structure | None: Retrieve the reply set on promise. promise must be in REPLIED and the returned structure is owned by promise

Added in version 1.14.

interrupt() → None: Interrupt waiting for a promise. This will wake up any waiters with INTERRUPTED. Called when the consumer does not want the value produced anymore.

Added in version 1.14.

reply(s: Structure | None = None) → None

Set a reply on promise. This will wake up any waiters with 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.

Added in version 1.14.

Parameters:: s – a Structure with the the reply contents

wait() → PromiseResult: Wait for promise to move out of the PENDING state. If promise is not in PENDING then it will return immediately with the current result.

Added in version 1.14.

Fields

class Promise

parent: Parent MiniObject