GstPromise: GStreamer Core Reference Manual

## GstPromise GstPromise — a miniobject for future/promise-like functionality |

## Functions

void | (*GstPromiseChangeFunc) ()
GstPromise * | gst_promise_new ()
GstPromise * | gst_promise_new_with_change_func ()
GstPromise * | gst_promise_ref ()
void | gst_promise_unref ()
GstPromiseResult | gst_promise_wait ()
void | gst_promise_reply ()
void | gst_promise_interrupt ()
void | gst_promise_expire ()
const GstStructure * | gst_promise_get_reply ()

## Types and Values

enum | GstPromiseResult
struct | GstPromise

## Object Hierarchy

        GBoxed
        ╰── GstPromise

## Includes

    #include <gst/gst.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