Copyright | Will Thompson and Iñaki García Etxebarria |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
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:
- That
promiseReply
andpromiseInterrupt
cannot be called afterpromiseExpire
- That
promiseReply
andpromiseInterrupt
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
- newtype Promise = Promise (ManagedPtr Promise)
- newZeroPromise :: MonadIO m => m Promise
- promiseExpire :: (HasCallStack, MonadIO m) => Promise -> m ()
- promiseGetReply :: (HasCallStack, MonadIO m) => Promise -> m (Maybe Structure)
- promiseInterrupt :: (HasCallStack, MonadIO m) => Promise -> m ()
- promiseNew :: (HasCallStack, MonadIO m) => m Promise
- promiseNewWithChangeFunc :: (HasCallStack, MonadIO m) => PromiseChangeFunc -> m Promise
- promiseReply :: (HasCallStack, MonadIO m) => Promise -> Maybe Structure -> m ()
- promiseWait :: (HasCallStack, MonadIO m) => Promise -> m PromiseResult
- getPromiseParent :: MonadIO m => Promise -> m MiniObject
Exported types
Memory-managed wrapper type.
Instances
Eq Promise Source # | |
GBoxed Promise Source # | |
Defined in GI.Gst.Structs.Promise | |
ManagedPtrNewtype Promise Source # | |
Defined in GI.Gst.Structs.Promise toManagedPtr :: Promise -> ManagedPtr Promise | |
TypedObject Promise Source # | |
Defined in GI.Gst.Structs.Promise | |
HasParentTypes Promise Source # | |
Defined in GI.Gst.Structs.Promise | |
tag ~ 'AttrSet => Constructible Promise tag Source # | |
IsGValue (Maybe Promise) Source # | Convert |
Defined in GI.Gst.Structs.Promise gvalueGType_ :: IO GType gvalueSet_ :: Ptr GValue -> Maybe Promise -> IO () gvalueGet_ :: Ptr GValue -> IO (Maybe Promise) | |
type ParentTypes Promise Source # | |
Defined in GI.Gst.Structs.Promise |
Methods
Click to display all available methods, including inherited ones
expire
:: (HasCallStack, MonadIO m) | |
=> 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
:: (HasCallStack, MonadIO m) | |
=> Promise |
|
-> m (Maybe Structure) | Returns: The reply set on |
Retrieve the reply set on promise
. promise
must be in
PromiseResultReplied
and the returned structure is owned by promise
Since: 1.14
interrupt
:: (HasCallStack, MonadIO m) | |
=> 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
:: (HasCallStack, MonadIO m) | |
=> m Promise | Returns: a new |
No description available in the introspection data.
Since: 1.14
newWithChangeFunc
promiseNewWithChangeFunc Source #
:: (HasCallStack, MonadIO m) | |
=> PromiseChangeFunc |
|
-> m Promise | Returns: a new |
func
will be called exactly once when transitioning out of
PromiseResultPending
into any of the other PromiseResult
states.
Since: 1.14
reply
:: (HasCallStack, MonadIO m) | |
=> Promise |
|
-> Maybe Structure |
|
-> 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
:: (HasCallStack, MonadIO m) | |
=> 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