gi-gst-1.0.19: GStreamer bindings

CopyrightWill Thompson Iñaki García Etxebarria and Jonas Platte
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria (inaki@blueleaf.cc)
Safe HaskellNone
LanguageHaskell2010

GI.Gst.Structs.Promise

Contents

Description

The Promise object implements the container for values that may be available later. i.e. a Future or a Promise in <ulink url="https://en.wikipedia.org/wiki/Futures_and_promises">https://en.wikipedia.org/wiki/Futures_and_promises</ulink> 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. 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 'GI.Gst.Enums.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

Synopsis

Exported types

newtype Promise Source #

Memory-managed wrapper type.

Constructors

Promise (ManagedPtr Promise) 
Instances
BoxedObject Promise Source # 
Instance details

Defined in GI.Gst.Structs.Promise

Methods

boxedType :: Promise -> IO GType #

tag ~ AttrSet => Constructible Promise tag Source # 
Instance details

Defined in GI.Gst.Structs.Promise

Methods

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

newZeroPromise :: MonadIO m => m Promise Source #

Construct a Promise struct initialized to zero.

noPromise :: Maybe Promise Source #

A convenience alias for Nothing :: Maybe Promise.

Methods

expire

promiseExpire Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> Promise

promise: a Promise

-> m 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 Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> m Promise

Returns: a new Promise

No description available in the introspection data.

Since: 1.14

newWithChangeFunc

promiseNewWithChangeFunc Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> Promise

promise: a Promise

-> 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 Source #

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 Source #

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

get promise #parent