Gst.Promise

Fields

Name	Type	Access	Description
parent	Gst.MiniObject	r/w	parent Gst.MiniObject

Methods

class	new ()
class	new_with_change_func (func, *user_data)
	expire ()
	get_reply ()
	interrupt ()
	reply (s)
	wait ()

Details

class Gst.Promise

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

That Gst.Promise.reply() and Gst.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. Gst.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 Gst.Promise.

New in version 1.14.

classmethod new()

Returns:a new Gst.Promise Return type:Gst.Promise

New in version 1.14.

classmethod new_with_change_func(func, *user_data)

Parameters:

• func (Gst.PromiseChangeFunc) – a Gst.PromiseChangeFunc to call
• user_data (object or None) – argument to call func with

Returns:

a new Gst.Promise

Return type:

Gst.Promise

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

New in version 1.14.

expire()

Expire a self. This will wake up any waiters with Gst.PromiseResult.EXPIRED. Called by a message loop when the parent message is handled and/or destroyed (possibly unanswered).

New in version 1.14.

get_reply()

Returns:The reply set on self Return type:Gst.Structure or None

Retrieve the reply set on self. self must be in Gst.PromiseResult.REPLIED and the returned structure is owned by self

New in version 1.14.

interrupt()

Interrupt waiting for a self. This will wake up any waiters with Gst.PromiseResult.INTERRUPTED. Called when the consumer does not want the value produced anymore.

New in version 1.14.

reply(s)

Parameters:s (Gst.Structure or None) – a Gst.Structure with the the reply contents

Set a reply on self. This will wake up any waiters with Gst.PromiseResult.REPLIED. Called by the producer of the value to indicate success (or failure).

If self has already been interrupted by the consumer, then this reply is not visible to the consumer.

New in version 1.14.

wait()

Returns:the result of the promise Return type:Gst.PromiseResult

Wait for self to move out of the Gst.PromiseResult.PENDING state. If self is not in Gst.PromiseResult.PENDING then it will return immediately with the current result.

New in version 1.14.