Iterator

class Iterator(*args, **kwargs)

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, get_object()), 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:

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);

Constructors

class Iterator

classmethod new_single(type: type, object: Any) → Iterator

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.

Parameters:

type – Type of the passed object
object – object that this iterator should return

Methods

class Iterator

filter(func: Callable[[None, None], int], user_data: Any) → Iterator

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 user_data. func should return 0 for elements that should be included in the filtered iterator.

When this iterator is freed, it will also be freed.

Parameters:

func – the compare function to select elements
user_data – user data passed to the compare function

find_custom(func: Callable[[...], int], *user_data: Any) → tuple[bool, Any]

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 user_data. 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.

Parameters:

func – the compare function to use
user_data – user data passed to the compare function

fold(func: Callable[[...], bool], ret: Any, *user_data: Any) → IteratorResult

Folds func over the elements of iter. That is to say, func will be called as func (object, ret, user_data) 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 foreach() and find_custom() operations.

The fold will proceed as long as func returns True. When the iterator has no more arguments, DONE will be returned. If func returns False, the fold will stop, and OK will be returned. Errors or resyncs will cause fold to return ERROR or RESYNC as appropriate.

The iterator will not be freed.

Parameters:

func – the fold function
ret – the seed value passed to the fold function
user_data – user data passed to the fold function

foreach(func: Callable[[...], None], *user_data: Any) → IteratorResult

Iterate over all element of it and call the given function func for each element.

Parameters:

func – the function to call for each element.
user_data – user data passed to the function

free() → None

Free the iterator.

MT safe.

next() → tuple[IteratorResult, Any]

Get the next item from the iterator in elem.

Only when this function returns OK, elem will contain a valid value. elem must have been initialized to the type of the iterator or initialized to zeroes with unset(). The caller is responsible for unsetting or resetting elem with unset() or reset() after usage.

When this function returns DONE, no more elements can be retrieved from it.

A return value of RESYNC indicates that the element list was concurrently updated. The user of it should call resync() to get the newly updated list.

A return value of ERROR indicates an unrecoverable fatal error.

push(other: Iterator) → None

Pushes other iterator onto it. All calls performed on it are forwarded to other. If other returns DONE, 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 resync() is called on it, other will automatically be popped.

MT safe.

Parameters:: other – The Iterator to push

resync() → None

Resync the iterator. this function is mostly called after next() returned RESYNC.

When an iterator was pushed on it, it will automatically be popped again with this function.

MT safe.

Fields

class Iterator

cookie: The cookie; the value of the master_cookie when this iterator was created.

item: The function to be called for each item retrieved

lock: The lock protecting the data structure and the cookie.

master_cookie: A pointer to the master cookie.

pushed: The iterator that is currently pushed with push()

size: The size of the iterator

type: The type of the object that this iterator will return