Class Iterator

java.lang.Object
org.javagi.base.ProxyInstance
org.freedesktop.gstreamer.gst.Iterator
All Implemented Interfaces:
Proxy
@Generated("org.javagi.JavaGI") public class Iterator extends ProxyInstance

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

  • Constructor Details

    • Iterator

      public Iterator(MemorySegment address)
      Create a Iterator proxy instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • Iterator

      public Iterator(int size, Type type, Mutex lock, MemorySegment masterCookie, @Nullable IteratorCopyFunction copy, @Nullable IteratorNextFunction next, @Nullable IteratorItemFunction item, @Nullable IteratorResyncFunction resync, @Nullable IteratorFreeFunction free)

      Create a new iterator. This function is mainly used for objects implementing the next/resync/free function to iterate a data structure.

      For each item retrieved, the item function is called with the lock held. The free function is called when the iterator is freed.

      Parameters:
      size - the size of the iterator structure
      type - GType of children
      lock - pointer to a GMutex.
      masterCookie - pointer to a guint32 that is changed when the items in the iterator changed.
      copy - copy function
      next - function to get next item
      item - function to call on each item retrieved
      resync - function to resync the iterator
      free - function to free the iterator

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the Iterator class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • readCopy

      public @Nullable IteratorCopyFunction readCopy()
      Read the value of the field copy.
      Returns:
      The value of the field copy

    • writeCopy

      public void writeCopy(@Nullable IteratorCopyFunction copy, Arena _arena)
      Write a value in the field copy.
      Parameters:
      copy - The new value for the field copy
      _arena - to control the memory allocation scope

    • readNext

      public @Nullable IteratorNextFunction readNext()
      Read the value of the field next.
      Returns:
      The value of the field next

    • writeNext

      public void writeNext(@Nullable IteratorNextFunction next, Arena _arena)
      Write a value in the field next.
      Parameters:
      next - The new value for the field next
      _arena - to control the memory allocation scope

    • readItem

      public @Nullable IteratorItemFunction readItem()
      Read the value of the field item.
      Returns:
      The value of the field item

    • writeItem

      public void writeItem(@Nullable IteratorItemFunction item, Arena _arena)
      Write a value in the field item.
      Parameters:
      item - The new value for the field item
      _arena - to control the memory allocation scope

    • readResync

      public @Nullable IteratorResyncFunction readResync()
      Read the value of the field resync.
      Returns:
      The value of the field resync

    • writeResync

      public void writeResync(@Nullable IteratorResyncFunction resync, Arena _arena)
      Write a value in the field resync.
      Parameters:
      resync - The new value for the field resync
      _arena - to control the memory allocation scope

    • readFree

      public @Nullable IteratorFreeFunction readFree()
      Read the value of the field free.
      Returns:
      The value of the field free

    • writeFree

      public void writeFree(@Nullable IteratorFreeFunction free, Arena _arena)
      Write a value in the field free.
      Parameters:
      free - The new value for the field free
      _arena - to control the memory allocation scope

    • readPushed

      public Iterator readPushed()
      Read the value of the field pushed.
      Returns:
      The value of the field pushed

    • writePushed

      public void writePushed(Iterator pushed)
      Write a value in the field pushed.
      Parameters:
      pushed - The new value for the field pushed

    • readType

      public Type readType()
      Read the value of the field type.
      Returns:
      The value of the field type

    • writeType

      public void writeType(Type type)
      Write a value in the field type.
      Parameters:
      type - The new value for the field type

    • readLock

      public Mutex readLock()
      Read the value of the field lock.
      Returns:
      The value of the field lock

    • writeLock

      public void writeLock(Mutex lock)
      Write a value in the field lock.
      Parameters:
      lock - The new value for the field lock

    • readCookie

      public int readCookie()
      Read the value of the field cookie.
      Returns:
      The value of the field cookie

    • writeCookie

      public void writeCookie(int cookie)
      Write a value in the field cookie.
      Parameters:
      cookie - The new value for the field cookie

    • readMasterCookie

      public MemorySegment readMasterCookie()
      Read the value of the field master_cookie.
      Returns:
      The value of the field master_cookie

    • writeMasterCookie

      public void writeMasterCookie(MemorySegment masterCookie)
      Write a value in the field master_cookie.
      Parameters:
      masterCookie - The new value for the field master_cookie

    • readSize

      public int readSize()
      Read the value of the field size.
      Returns:
      The value of the field size

    • writeSize

      public void writeSize(int size)
      Write a value in the field size.
      Parameters:
      size - The new value for the field size

    • list

      public static Iterator list(Type type, Mutex lock, MemorySegment masterCookie, List<MemorySegment>[] list, GObject owner, @Nullable IteratorItemFunction item)

      Create a new iterator designed for iterating list.

      The list you iterate is usually part of a data structure owner and is protected with lock.

      The iterator will use lock to retrieve the next item of the list and it will then call the item function before releasing lock again.

      When a concurrent update to the list is performed, usually by owner while holding lock, masterCookie will be updated. The iterator implementation will notice the update of the cookie and will return IteratorResult.RESYNC to the user of the iterator in the next call to gst_iterator_next().

      Parameters:
      type - GType of elements
      lock - pointer to a GMutex protecting the list.
      masterCookie - pointer to a guint32 that is incremented when the list is changed.
      list - pointer to the list
      owner - object owning the list
      item - function to call on each item retrieved
      Returns:

      the new GstIterator for list.

      MT safe.

    • single

      public static Iterator single(Type type, Value object)
      This GstIterator is a convenient iterator for the common case where a GstIterator needs to be returned but only a single object has to be considered. This happens often for the GstPadIterIntLinkFunction.
      Parameters:
      type - GType of the passed object
      object - object that this iterator should return
      Returns:
      the new GstIterator for object.

    • copy

      public Iterator copy()
      Copy the iterator and its state.
      Returns:
      a new copy of it.

    • filter

      public Iterator filter(@Nullable CompareFunc func, Value userData)

      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 GValue 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, this Iterator will also be freed.

      Parameters:
      func - the compare function to select elements
      userData - user data passed to the compare function
      Returns:

      a new GstIterator.

      MT safe.

    • findCustom

      public boolean findCustom(@Nullable CompareFunc func, Value elem)

      Find the first element in this Iterator 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.

      Parameters:
      func - the compare function to use
      elem - pointer to a GValue where to store the result
      Returns:

      Returns true if the element was found, else false.

      MT safe.

    • fold

      public IteratorResult fold(@Nullable IteratorFoldFunction func, Value ret)

      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 gst_iterator_foreach() and gst_iterator_find_custom() operations.

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

      The iterator will not be freed.

      Parameters:
      func - the fold function
      ret - the seed value passed to the fold function
      Returns:

      A GstIteratorResult, as described above.

      MT safe.

    • foreach

      public IteratorResult foreach(@Nullable IteratorForeachFunction func)
      Iterate over all element of this Iterator and call the given function func for each element.
      Parameters:
      func - the function to call for each element.
      Returns:

      the result call to gst_iterator_fold(). The iterator will not be freed.

      MT safe.

    • free

      public void free()

      Free the iterator.

      MT safe.

    • next

      public IteratorResult next(Value elem)

      Get the next item from the iterator in elem.

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

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

      A return value of IteratorResult.RESYNC indicates that the element list was concurrently updated. The user of this Iterator should call gst_iterator_resync() to get the newly updated list.

      A return value of IteratorResult.ERROR indicates an unrecoverable fatal error.

      Parameters:
      elem - pointer to hold next element
      Returns:

      The result of the iteration. Unset elem after usage.

      MT safe.

    • push

      public void push(Iterator other)

      Pushes other iterator onto it. All calls performed on this Iterator are forwarded to other. If other returns IteratorResult.DONE, it is popped again and calls are handled by this Iterator again.

      This function is mainly used by objects implementing the iterator next function to recurse into substructures.

      When gst_iterator_resync() is called on it, other will automatically be popped.

      MT safe.

      Parameters:
      other - The GstIterator to push

    • resync

      public void resync()

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

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

      MT safe.