# GstPromise

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. The exact value returned is defined by the API contract of the producer and NULL 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_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 GstPromise'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 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.

## GstPromise

### Members

`parent` (GstMiniObject) –

parent GstMiniObject

Since : 1.14

## Gst.Promise

### Members

`parent` (Gst.MiniObject) –

parent Gst.MiniObject

Since : 1.14

## Gst.Promise

### Members

`parent` (Gst.MiniObject) –

parent Gst.MiniObject

Since : 1.14

### Constructors

#### gst_promise_new

    GstPromise *
    gst_promise_new ()

Returns –

a new GstPromise

Since : 1.14

#### Gst.Promise.prototype.new

    function Gst.Promise.prototype.new(): {
        // javascript wrapper for 'gst_promise_new'
    }

Returns (Gst.Promise) –

a new Gst.Promise

Since : 1.14

#### Gst.Promise.new

    def Gst.Promise.new ():
        #python wrapper for 'gst_promise_new'

Returns (Gst.Promise) –

a new Gst.Promise

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` ( [scope notified][closure]) –

a GstPromiseChangeFunc to call

`user_data` –

argument to call func with

`notify` –

notification function that user_data is no longer needed

Returns –

a new GstPromise

Since : 1.14

#### Gst.Promise.prototype.new_with_change_func

    function Gst.Promise.prototype.new_with_change_func(func: Gst.PromiseChangeFunc, user_data: Object): {
        // javascript wrapper for 'gst_promise_new_with_change_func'
    }

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

Parameters:

`func` (Gst.PromiseChangeFunc) –

a Gst.PromiseChangeFunc to call

`user_data` (Object) –

argument to call func with

Returns (Gst.Promise) –

a new Gst.Promise

Since : 1.14

#### Gst.Promise.new_with_change_func

    def Gst.Promise.new_with_change_func (func, *user_data):
        #python wrapper for 'gst_promise_new_with_change_func'

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

Parameters:

`func` (Gst.PromiseChangeFunc) –

a Gst.PromiseChangeFunc to call

`user_data` (variadic) –

argument to call func with

Returns (Gst.Promise) –

a new Gst.Promise

Since : 1.14

### Methods

#### gst_promise_expire

    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.prototype.expire

    function Gst.Promise.prototype.expire(): {
        // javascript wrapper for 'gst_promise_expire'
    }

Expire a promise. 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).

Parameters:

`promise` (Gst.Promise) –

a Gst.Promise

Since : 1.14

#### Gst.Promise.expire

    def Gst.Promise.expire (self):
        #python wrapper for 'gst_promise_expire'

Expire a promise. 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).

Parameters:

`promise` (Gst.Promise) –

a Gst.Promise

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 ( [transfer: none][nullable]) –

The reply set on promise

Since : 1.14

#### Gst.Promise.prototype.get_reply

    function Gst.Promise.prototype.get_reply(): {
        // javascript wrapper for 'gst_promise_get_reply'
    }

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

Parameters:

`promise` (Gst.Promise) –

a Gst.Promise

Returns (Gst.Structure) –

The reply set on promise

Since : 1.14

#### Gst.Promise.get_reply

    def Gst.Promise.get_reply (self):
        #python wrapper for 'gst_promise_get_reply'

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

Parameters:

`promise` (Gst.Promise) –

a Gst.Promise

Returns (Gst.Structure) –

The reply set on promise

Since : 1.14

#### gst_promise_interrupt

    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.prototype.interrupt

    function Gst.Promise.prototype.interrupt(): {
        // javascript wrapper for 'gst_promise_interrupt'
    }

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

Parameters:

`promise` (Gst.Promise) –

a Gst.Promise

Since : 1.14

#### Gst.Promise.interrupt

    def Gst.Promise.interrupt (self):
        #python wrapper for 'gst_promise_interrupt'

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

Parameters:

`promise` (Gst.Promise) –

a Gst.Promise

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 ( [transfer: full]) –

promise

Since : 1.14

#### Gst.Promise.prototype.ref

    function Gst.Promise.prototype.ref(): {
        // javascript wrapper for 'gst_promise_ref'
    }

Increases the refcount of the given promise by one.

Parameters:

`promise` (Gst.Promise) –

a Gst.Promise.

Returns (Gst.Promise) –

promise

Since : 1.14

#### Gst.Promise.ref

    def Gst.Promise.ref (self):
        #python wrapper for 'gst_promise_ref'

Increases the refcount of the given promise by one.

Parameters:

`promise` (Gst.Promise) –

a Gst.Promise.

Returns (Gst.Promise) –

promise

Since : 1.14

#### gst_promise_reply

    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` ( [allow-none]) –

a GstPromise

`s` ( [transfer: full][nullable]) –

a GstStructure with the the reply contents

Since : 1.14

#### Gst.Promise.prototype.reply

    function Gst.Promise.prototype.reply(s: Gst.Structure): {
        // javascript wrapper for 'gst_promise_reply'
    }

Set a reply on promise. This will wake up any waiters with Gst.PromiseResult.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` (Gst.Promise) –

a Gst.Promise

`s` (Gst.Structure) –

a Gst.Structure with the the reply contents

Since : 1.14

#### Gst.Promise.reply

    def Gst.Promise.reply (self, s):
        #python wrapper for 'gst_promise_reply'

Set a reply on promise. This will wake up any waiters with Gst.PromiseResult.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` (Gst.Promise) –

a Gst.Promise

`s` (Gst.Structure) –

a Gst.Structure with the the reply contents

Since : 1.14

#### gst_promise_unref

    gst_promise_unref (GstPromise * promise)

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

Parameters:

`promise` ( [transfer: full]) –

a GstPromise.

Since : 1.14

#### Gst.Promise.prototype.unref

    function Gst.Promise.prototype.unref(): {
        // javascript wrapper for 'gst_promise_unref'
    }

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

Parameters:

`promise` (Gst.Promise) –

a Gst.Promise.

Since : 1.14

#### Gst.Promise.unref

    def Gst.Promise.unref (self):
        #python wrapper for 'gst_promise_unref'

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

Parameters:

`promise` (Gst.Promise) –

a Gst.Promise.

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.prototype.wait

    function Gst.Promise.prototype.wait(): {
        // javascript wrapper for 'gst_promise_wait'
    }

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

Parameters:

`promise` (Gst.Promise) –

a Gst.Promise

Returns (Gst.PromiseResult) –

the result of the promise

Since : 1.14

#### Gst.Promise.wait

    def Gst.Promise.wait (self):
        #python wrapper for 'gst_promise_wait'

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

Parameters:

`promise` (Gst.Promise) –

a Gst.Promise

Returns (Gst.PromiseResult) –

the result of the promise

Since : 1.14

## Functions

### gst_clear_promise

    gst_clear_promise (GstPromise ** promise_ptr)

Clears a reference to a GstPromise.

promise_ptr must not be `NULL`.

If the reference is `NULL` then this function does nothing. Otherwise, the reference count of the promise is decreased and the pointer is set to `NULL`.

Parameters:

`promise_ptr` –

a pointer to a GstPromise reference

Since : 1.24

## Enumerations

### GstPromiseResult

The result of a GstPromise

##### Members

`GST_PROMISE_RESULT_PENDING` (0) –

Initial state. Waiting for transition to any other state.

`GST_PROMISE_RESULT_INTERRUPTED` (1) –

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

`GST_PROMISE_RESULT_REPLIED` (2) –

A producer marked a reply

`GST_PROMISE_RESULT_EXPIRED` (3) –

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

Since : 1.14

### Gst.PromiseResult

The result of a Gst.Promise

##### Members

`Gst.PromiseResult.PENDING` (0) –

Initial state. Waiting for transition to any other state.

`Gst.PromiseResult.INTERRUPTED` (1) –

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

`Gst.PromiseResult.REPLIED` (2) –

A producer marked a reply

`Gst.PromiseResult.EXPIRED` (3) –

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

Since : 1.14

### Gst.PromiseResult

The result of a Gst.Promise

##### Members

`Gst.PromiseResult.PENDING` (0) –

Initial state. Waiting for transition to any other state.

`Gst.PromiseResult.INTERRUPTED` (1) –

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

`Gst.PromiseResult.REPLIED` (2) –

A producer marked a reply

`Gst.PromiseResult.EXPIRED` (3) –

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

Since : 1.14

## Callbacks

### GstPromiseChangeFunc

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

Parameters:

`promise` –

a GstPromise

`user_data` ( [closure]) –

user data

Since : 1.14

### Gst.PromiseChangeFunc

    function Gst.PromiseChangeFunc(promise: Gst.Promise, user_data: Object): {
        // javascript wrapper for 'GstPromiseChangeFunc'
    }

Parameters:

`promise` (Gst.Promise) –

a Gst.Promise

`user_data` (Object) –

user data

Since : 1.14

### Gst.PromiseChangeFunc

    def Gst.PromiseChangeFunc (promise, *user_data):
        #python wrapper for 'GstPromiseChangeFunc'

Parameters:

`promise` (Gst.Promise) –

a Gst.Promise

`user_data` (variadic) –

user data

Since : 1.14

The results of the search are