GstPromise

GstPromise — a miniobject for future/promise-like functionality

Functions

Types and Values

Object Hierarchy

    GBoxed
    ╰── GstPromise

Includes

#include <gst/gstprotection.h>

Description

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_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_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_PROMISE_RESULT_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 GstBus. A callback can also be installed at GstPromise creation for result changes with gst_promise_new_with_change_func(). The change callback can be used to chain GstPromises's together as in the following example.

1
2
3
4
5
6
7
8
9
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_PROMISE_RESULT_PENDING and only ever transitions once into one of the other GstPromiseResult'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:

  1. That gst_promise_reply() and gst_promise_interrupt() cannot be called after gst_promise_expire()

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

Functions

GstPromiseChangeFunc ()

void
(*GstPromiseChangeFunc) (GstPromise *promise,
                         gpointer user_data);

Parameters

promise

a GstPromise

 

user_data

user data.

[closure]

Since: 1.14


gst_promise_new ()

GstPromise *
gst_promise_new (void);

Returns

a new GstPromise

Since: 1.14


gst_promise_new_with_change_func ()

GstPromise *
gst_promise_new_with_change_func (GstPromiseChangeFunc func,
                                  gpointer user_data,
                                  GDestroyNotify notify);

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

Parameters

func

a GstPromiseChangeFunc to call.

[scope notified]

user_data

argument to call func with.

[closure]

notify

notification function that user_data is no longer needed

 

Returns

a new GstPromise

Since: 1.14


gst_promise_ref ()

GstPromise *
gst_promise_ref (GstPromise *promise);

Increases the refcount of the given promise by one.

Parameters

promise

a GstPromise.

 

Returns

promise .

[transfer full]

Since: 1.14


gst_promise_unref ()

void
gst_promise_unref (GstPromise *promise);

Decreases the refcount of the promise. If the refcount reaches 0, the promise will be freed.

Parameters

promise

a GstPromise.

[transfer full]

Since: 1.14


gst_promise_wait ()

GstPromiseResult
gst_promise_wait (GstPromise *promise);

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.

Parameters

promise

a GstPromise

 

Returns

the result of the promise

Since: 1.14


gst_promise_reply ()

void
gst_promise_reply (GstPromise *promise,
                   GstStructure *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).

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

Parameters

promise

a GstPromise.

[allow-none]

s

a GstStructure with the the reply contents.

[transfer full]

Since: 1.14


gst_promise_interrupt ()

void
gst_promise_interrupt (GstPromise *promise);

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.

Parameters

promise

a GstPromise

 

Since: 1.14


gst_promise_expire ()

void
gst_promise_expire (GstPromise *promise);

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).

Parameters

promise

a GstPromise

 

Since: 1.14


gst_promise_get_reply ()

const GstStructure *
gst_promise_get_reply (GstPromise *promise);

Retrieve the reply set on promise . promise must be in GST_PROMISE_RESULT_REPLIED and the returned structure is owned by promise

Parameters

promise

a GstPromise

 

Returns

The reply set on promise .

[transfer none]

Since: 1.14

Types and Values

enum GstPromiseResult

The result of a GstPromise

Members

GST_PROMISE_RESULT_PENDING

Initial state. Waiting for transition to any other state.

 

GST_PROMISE_RESULT_INTERRUPTED

Interrupted by the consumer as it doesn't want the value anymore.

 

GST_PROMISE_RESULT_REPLIED

A producer marked a reply

 

GST_PROMISE_RESULT_EXPIRED

The promise expired (the carrying object lost all refs) and the promise will never be fulfilled.

 

Since: 1.14


struct GstPromise

struct GstPromise {
  GstMiniObject         parent;
};

Members

GstMiniObject parent;

parent GstMiniObject

 

Since: 1.14