GI.Gst.Structs.Promise

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 promiseNew 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 promiseReply. The exact value returned is defined by the API contract of the producer and Nothing may be a valid reply. promiseInterrupt is for the consumer to indicate to the producer that the value is not needed anymore and producing that value can stop. The gSTPROMISERESULTEXPIRED state set by a call to promiseExpire 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 promiseNewWithChangeFunc. The change callback can be used to chain GstPromises's together as in the following example.

C code

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 PromiseResultPending and only ever transitions once into one of the other PromiseResult's.

In order to support multi-threaded code, promiseReply, promiseInterrupt and promiseExpire 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 promiseReply and promiseInterrupt cannot be called after promiseExpire
2. That promiseReply and promiseInterrupt cannot be called twice.

The change function set with promiseNewWithChangeFunc is called directly from either the promiseReply, promiseInterrupt or promiseExpire 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.

Since: 1.14

Exported types

newtype Promise

Memory-managed wrapper type.

Constructors

Promise (ManagedPtr Promise)

Instances

Eq Promise

Defined in GI.Gst.Structs.Promise

Methods

(==) :: Promise -> Promise -> Bool

(/=) :: Promise -> Promise -> Bool

GBoxed Promise

Defined in GI.Gst.Structs.Promise

ManagedPtrNewtype Promise

Defined in GI.Gst.Structs.Promise

Methods

toManagedPtr :: Promise -> ManagedPtr Promise

TypedObject Promise

Defined in GI.Gst.Structs.Promise

Methods

glibType :: IO GType

HasParentTypes Promise

Defined in GI.Gst.Structs.Promise

tag ~ 'AttrSet => Constructible Promise tag

Defined in GI.Gst.Structs.Promise

Methods

new :: MonadIO m => (ManagedPtr Promise -> Promise) -> [AttrOp Promise tag] -> m Promise

IsGValue (Maybe Promise)

Convert Promise to and from GValue. See toGValue and fromGValue.

Defined in GI.Gst.Structs.Promise

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe Promise -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe Promise)

type ParentTypes Promise

Defined in GI.Gst.Structs.Promise

type ParentTypes Promise = '[] :: [Type]

newZeroPromise :: MonadIO m => m Promise

Construct a Promise struct initialized to zero.

Methods

Click to display all available methods, including inherited ones

Methods

expire, interrupt, reply, wait.

Getters

getReply.

Setters

None.

expire

promiseExpire

Arguments

:: (HasCallStack, MonadIO m)

=> Promise

promise: a Promise

-> m ()

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

Since: 1.14

getReply

promiseGetReply

Arguments

:: (HasCallStack, MonadIO m)

=> Promise

promise: a Promise

-> m (Maybe Structure)

Returns: The reply set on promise

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

Since: 1.14

interrupt

promiseInterrupt

Arguments

:: (HasCallStack, MonadIO m)

=> Promise

promise: a Promise

-> m ()

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

Since: 1.14

new

promiseNew

Arguments

:: (HasCallStack, MonadIO m)

=> m Promise

Returns: a new Promise

No description available in the introspection data.

Since: 1.14

newWithChangeFunc

promiseNewWithChangeFunc

Arguments

:: (HasCallStack, MonadIO m)

=> PromiseChangeFunc

func: a PromiseChangeFunc to call

-> m Promise

Returns: a new Promise

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

Since: 1.14

reply

promiseReply

Arguments

:: (HasCallStack, MonadIO m)

=> Promise

promise: a Promise

-> Maybe Structure

s: a Structure with the the reply contents

-> m ()

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

Since: 1.14

wait

promiseWait

Arguments

:: (HasCallStack, MonadIO m)

=> Promise

promise: a Promise

-> m PromiseResult

Returns: the result of the promise

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

Since: 1.14

Properties

parent

parent MiniObject

getPromiseParent :: MonadIO m => Promise -> m MiniObject

Get the value of the “parent” field. When overloading is enabled, this is equivalent to

get promise #parent