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 |
A GstIterator is used to retrieve multiple objects from another object in a threadsafe way.
Various GStreamer objects provide access to their internal structures using an iterator.
Note that if calling a GstIterator function results in your code receiving
a refcounted object (with, say, valueGetObject
), the refcount for that
object will not be increased. Your code is responsible for taking a reference
if it wants to continue using it later.
The basic use pattern of an iterator is as follows:
C code
GstIterator *it = _get_iterator(object); GValue item = G_VALUE_INIT; done = FALSE; while (!done) { switch (gst_iterator_next (it, &item)) { case GST_ITERATOR_OK: ...get/use/change item here... g_value_reset (&item); break; case GST_ITERATOR_RESYNC: ...rollback changes to items... gst_iterator_resync (it); break; case GST_ITERATOR_ERROR: ...wrong parameters were given... done = TRUE; break; case GST_ITERATOR_DONE: done = TRUE; break; } } g_value_unset (&item); gst_iterator_free (it);
Synopsis
- newtype Iterator = Iterator (ManagedPtr Iterator)
- newZeroIterator :: MonadIO m => m Iterator
- iteratorCopy :: (HasCallStack, MonadIO m) => Iterator -> m Iterator
- iteratorFilter :: (HasCallStack, MonadIO m) => Iterator -> CompareFunc -> GValue -> m Iterator
- iteratorFindCustom :: (HasCallStack, MonadIO m) => Iterator -> CompareFunc -> m (Bool, GValue)
- iteratorFold :: (HasCallStack, MonadIO m) => Iterator -> IteratorFoldFunction -> GValue -> m IteratorResult
- iteratorForeach :: (HasCallStack, MonadIO m) => Iterator -> IteratorForeachFunction -> m IteratorResult
- iteratorFree :: (HasCallStack, MonadIO m) => Iterator -> m ()
- iteratorNewSingle :: (HasCallStack, MonadIO m) => GType -> GValue -> m Iterator
- iteratorNext :: (HasCallStack, MonadIO m) => Iterator -> m (IteratorResult, GValue)
- iteratorPush :: (HasCallStack, MonadIO m) => Iterator -> Iterator -> m ()
- iteratorResync :: (HasCallStack, MonadIO m) => Iterator -> m ()
- getIteratorCookie :: MonadIO m => Iterator -> m Word32
- setIteratorCookie :: MonadIO m => Iterator -> Word32 -> m ()
- clearIteratorCopy :: MonadIO m => Iterator -> m ()
- getIteratorCopy :: MonadIO m => Iterator -> m (Maybe IteratorCopyFunction)
- setIteratorCopy :: MonadIO m => Iterator -> FunPtr C_IteratorCopyFunction -> m ()
- clearIteratorFree :: MonadIO m => Iterator -> m ()
- getIteratorFree :: MonadIO m => Iterator -> m (Maybe IteratorFreeFunction)
- setIteratorFree :: MonadIO m => Iterator -> FunPtr C_IteratorFreeFunction -> m ()
- clearIteratorItem :: MonadIO m => Iterator -> m ()
- getIteratorItem :: MonadIO m => Iterator -> m (Maybe IteratorItemFunction)
- setIteratorItem :: MonadIO m => Iterator -> FunPtr C_IteratorItemFunction -> m ()
- clearIteratorLock :: MonadIO m => Iterator -> m ()
- getIteratorLock :: MonadIO m => Iterator -> m (Maybe Mutex)
- setIteratorLock :: MonadIO m => Iterator -> Ptr Mutex -> m ()
- getIteratorMasterCookie :: MonadIO m => Iterator -> m Word32
- setIteratorMasterCookie :: MonadIO m => Iterator -> Word32 -> m ()
- clearIteratorNext :: MonadIO m => Iterator -> m ()
- getIteratorNext :: MonadIO m => Iterator -> m (Maybe IteratorNextFunction)
- setIteratorNext :: MonadIO m => Iterator -> FunPtr C_IteratorNextFunction -> m ()
- clearIteratorPushed :: MonadIO m => Iterator -> m ()
- getIteratorPushed :: MonadIO m => Iterator -> m (Maybe Iterator)
- setIteratorPushed :: MonadIO m => Iterator -> Ptr Iterator -> m ()
- clearIteratorResync :: MonadIO m => Iterator -> m ()
- getIteratorResync :: MonadIO m => Iterator -> m (Maybe IteratorResyncFunction)
- setIteratorResync :: MonadIO m => Iterator -> FunPtr C_IteratorResyncFunction -> m ()
- getIteratorSize :: MonadIO m => Iterator -> m Word32
- setIteratorSize :: MonadIO m => Iterator -> Word32 -> m ()
- getIteratorType :: MonadIO m => Iterator -> m GType
- setIteratorType :: MonadIO m => Iterator -> GType -> m ()
Exported types
Memory-managed wrapper type.
Instances
Eq Iterator Source # | |
GBoxed Iterator Source # | |
Defined in GI.Gst.Structs.Iterator | |
ManagedPtrNewtype Iterator Source # | |
Defined in GI.Gst.Structs.Iterator toManagedPtr :: Iterator -> ManagedPtr Iterator | |
TypedObject Iterator Source # | |
Defined in GI.Gst.Structs.Iterator | |
HasParentTypes Iterator Source # | |
Defined in GI.Gst.Structs.Iterator | |
tag ~ 'AttrSet => Constructible Iterator tag Source # | |
IsGValue (Maybe Iterator) Source # | Convert |
Defined in GI.Gst.Structs.Iterator gvalueGType_ :: IO GType gvalueSet_ :: Ptr GValue -> Maybe Iterator -> IO () gvalueGet_ :: Ptr GValue -> IO (Maybe Iterator) | |
type ParentTypes Iterator Source # | |
Defined in GI.Gst.Structs.Iterator |
Methods
Click to display all available methods, including inherited ones
copy
:: (HasCallStack, MonadIO m) | |
=> Iterator |
|
-> m Iterator | Returns: a new copy of |
Copy the iterator and its state.
filter
:: (HasCallStack, MonadIO m) | |
=> Iterator |
|
-> CompareFunc |
|
-> GValue |
|
-> m Iterator | Returns: a new MT safe. |
Create a new iterator from an existing iterator. The new iterator
will only return those elements that match the given compare function func
.
The first parameter that is passed to func
is the Value
of the current
iterator element and the second parameter is userData
. func
should
return 0 for elements that should be included in the filtered iterator.
When this iterator is freed, it
will also be freed.
findCustom
:: (HasCallStack, MonadIO m) | |
=> Iterator |
|
-> CompareFunc |
|
-> m (Bool, GValue) | Returns: Returns MT safe. |
Find the first element in it
that matches the compare function func
.
func
should return 0 when the element is found. The first parameter
to func
will be the current element of the iterator and the
second parameter will be userData
.
The result will be stored in elem
if a result is found.
The iterator will not be freed.
This function will return False
if an error happened to the iterator
or if the element wasn't found.
fold
:: (HasCallStack, MonadIO m) | |
=> Iterator |
|
-> IteratorFoldFunction |
|
-> GValue |
|
-> m IteratorResult | Returns: A MT safe. |
Folds func
over the elements of iter
. That is to say, func
will be called
as func
(object, ret
, userData
) for each object in it
. The normal use
of this procedure is to accumulate the results of operating on the objects in
ret
.
This procedure can be used (and is used internally) to implement the
iteratorForeach
and iteratorFindCustom
operations.
The fold will proceed as long as func
returns True
. When the iterator has no
more arguments, IteratorResultDone
will be returned. If func
returns False
,
the fold will stop, and IteratorResultOk
will be returned. Errors or resyncs
will cause fold to return IteratorResultError
or IteratorResultResync
as
appropriate.
The iterator will not be freed.
foreach
:: (HasCallStack, MonadIO m) | |
=> Iterator |
|
-> IteratorForeachFunction |
|
-> m IteratorResult | Returns: the result call to MT safe. |
Iterate over all element of it
and call the given function func
for
each element.
free
:: (HasCallStack, MonadIO m) | |
=> Iterator |
|
-> m () |
Free the iterator.
MT safe.
newSingle
:: (HasCallStack, MonadIO m) | |
=> GType |
|
-> GValue |
|
-> m Iterator | Returns: the new |
This Iterator
is a convenient iterator for the common
case where a Iterator
needs to be returned but only
a single object has to be considered. This happens often
for the PadIterIntLinkFunction
.
next
:: (HasCallStack, MonadIO m) | |
=> Iterator |
|
-> m (IteratorResult, GValue) | Returns: The result of the iteration. Unset MT safe. |
Get the next item from the iterator in elem
.
Only when this function returns IteratorResultOk
, elem
will contain a valid
value. elem
must have been initialized to the type of the iterator or
initialized to zeroes with valueUnset
. The caller is responsible for
unsetting or resetting elem
with valueUnset
or valueReset
after usage.
When this function returns IteratorResultDone
, no more elements can be
retrieved from it
.
A return value of IteratorResultResync
indicates that the element list was
concurrently updated. The user of it
should call iteratorResync
to
get the newly updated list.
A return value of IteratorResultError
indicates an unrecoverable fatal error.
push
:: (HasCallStack, MonadIO m) | |
=> Iterator |
|
-> Iterator |
|
-> m () |
Pushes other
iterator onto it
. All calls performed on it
are
forwarded to other
. If other
returns IteratorResultDone
, it is
popped again and calls are handled by it
again.
This function is mainly used by objects implementing the iterator next function to recurse into substructures.
When iteratorResync
is called on it
, other
will automatically be
popped.
MT safe.
resync
:: (HasCallStack, MonadIO m) | |
=> Iterator |
|
-> m () |
Resync the iterator. this function is mostly called
after iteratorNext
returned IteratorResultResync
.
When an iterator was pushed on it
, it will automatically be popped again
with this function.
MT safe.
Properties
cookie
The cookie; the value of the master_cookie when this iterator was created.
getIteratorCookie :: MonadIO m => Iterator -> m Word32 Source #
Get the value of the “cookie
” field.
When overloading is enabled, this is equivalent to
get
iterator #cookie
setIteratorCookie :: MonadIO m => Iterator -> Word32 -> m () Source #
Set the value of the “cookie
” field.
When overloading is enabled, this is equivalent to
set
iterator [ #cookie:=
value ]
copy
The function to copy the iterator
clearIteratorCopy :: MonadIO m => Iterator -> m () Source #
Set the value of the “copy
” field to Nothing
.
When overloading is enabled, this is equivalent to
clear
#copy
getIteratorCopy :: MonadIO m => Iterator -> m (Maybe IteratorCopyFunction) Source #
Get the value of the “copy
” field.
When overloading is enabled, this is equivalent to
get
iterator #copy
setIteratorCopy :: MonadIO m => Iterator -> FunPtr C_IteratorCopyFunction -> m () Source #
Set the value of the “copy
” field.
When overloading is enabled, this is equivalent to
set
iterator [ #copy:=
value ]
free
The function to call when the iterator is freed
clearIteratorFree :: MonadIO m => Iterator -> m () Source #
Set the value of the “free
” field to Nothing
.
When overloading is enabled, this is equivalent to
clear
#free
getIteratorFree :: MonadIO m => Iterator -> m (Maybe IteratorFreeFunction) Source #
Get the value of the “free
” field.
When overloading is enabled, this is equivalent to
get
iterator #free
setIteratorFree :: MonadIO m => Iterator -> FunPtr C_IteratorFreeFunction -> m () Source #
Set the value of the “free
” field.
When overloading is enabled, this is equivalent to
set
iterator [ #free:=
value ]
item
The function to be called for each item retrieved
clearIteratorItem :: MonadIO m => Iterator -> m () Source #
Set the value of the “item
” field to Nothing
.
When overloading is enabled, this is equivalent to
clear
#item
getIteratorItem :: MonadIO m => Iterator -> m (Maybe IteratorItemFunction) Source #
Get the value of the “item
” field.
When overloading is enabled, this is equivalent to
get
iterator #item
setIteratorItem :: MonadIO m => Iterator -> FunPtr C_IteratorItemFunction -> m () Source #
Set the value of the “item
” field.
When overloading is enabled, this is equivalent to
set
iterator [ #item:=
value ]
lock
The lock protecting the data structure and the cookie.
clearIteratorLock :: MonadIO m => Iterator -> m () Source #
Set the value of the “lock
” field to Nothing
.
When overloading is enabled, this is equivalent to
clear
#lock
getIteratorLock :: MonadIO m => Iterator -> m (Maybe Mutex) Source #
Get the value of the “lock
” field.
When overloading is enabled, this is equivalent to
get
iterator #lock
setIteratorLock :: MonadIO m => Iterator -> Ptr Mutex -> m () Source #
Set the value of the “lock
” field.
When overloading is enabled, this is equivalent to
set
iterator [ #lock:=
value ]
masterCookie
A pointer to the master cookie.
getIteratorMasterCookie :: MonadIO m => Iterator -> m Word32 Source #
Get the value of the “master_cookie
” field.
When overloading is enabled, this is equivalent to
get
iterator #masterCookie
setIteratorMasterCookie :: MonadIO m => Iterator -> Word32 -> m () Source #
Set the value of the “master_cookie
” field.
When overloading is enabled, this is equivalent to
set
iterator [ #masterCookie:=
value ]
next
The function to get the next item in the iterator
clearIteratorNext :: MonadIO m => Iterator -> m () Source #
Set the value of the “next
” field to Nothing
.
When overloading is enabled, this is equivalent to
clear
#next
getIteratorNext :: MonadIO m => Iterator -> m (Maybe IteratorNextFunction) Source #
Get the value of the “next
” field.
When overloading is enabled, this is equivalent to
get
iterator #next
setIteratorNext :: MonadIO m => Iterator -> FunPtr C_IteratorNextFunction -> m () Source #
Set the value of the “next
” field.
When overloading is enabled, this is equivalent to
set
iterator [ #next:=
value ]
pushed
The iterator that is currently pushed with iteratorPush
clearIteratorPushed :: MonadIO m => Iterator -> m () Source #
Set the value of the “pushed
” field to Nothing
.
When overloading is enabled, this is equivalent to
clear
#pushed
getIteratorPushed :: MonadIO m => Iterator -> m (Maybe Iterator) Source #
Get the value of the “pushed
” field.
When overloading is enabled, this is equivalent to
get
iterator #pushed
setIteratorPushed :: MonadIO m => Iterator -> Ptr Iterator -> m () Source #
Set the value of the “pushed
” field.
When overloading is enabled, this is equivalent to
set
iterator [ #pushed:=
value ]
resync
The function to call when a resync is needed.
clearIteratorResync :: MonadIO m => Iterator -> m () Source #
Set the value of the “resync
” field to Nothing
.
When overloading is enabled, this is equivalent to
clear
#resync
getIteratorResync :: MonadIO m => Iterator -> m (Maybe IteratorResyncFunction) Source #
Get the value of the “resync
” field.
When overloading is enabled, this is equivalent to
get
iterator #resync
setIteratorResync :: MonadIO m => Iterator -> FunPtr C_IteratorResyncFunction -> m () Source #
Set the value of the “resync
” field.
When overloading is enabled, this is equivalent to
set
iterator [ #resync:=
value ]
size
the size of the iterator
getIteratorSize :: MonadIO m => Iterator -> m Word32 Source #
Get the value of the “size
” field.
When overloading is enabled, this is equivalent to
get
iterator #size
setIteratorSize :: MonadIO m => Iterator -> Word32 -> m () Source #
Set the value of the “size
” field.
When overloading is enabled, this is equivalent to
set
iterator [ #size:=
value ]
type
The type of the object that this iterator will return
getIteratorType :: MonadIO m => Iterator -> m GType Source #
Get the value of the “type
” field.
When overloading is enabled, this is equivalent to
get
iterator #type
setIteratorType :: MonadIO m => Iterator -> GType -> m () Source #
Set the value of the “type
” field.
When overloading is enabled, this is equivalent to
set
iterator [ #type:=
value ]