Class AsyncQueue

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.glib.AsyncQueue
All Implemented Interfaces:
Proxy
@Generated("org.javagi.JavaGI") public class AsyncQueue extends ProxyInstance

An opaque data structure which represents an asynchronous queue.

It should only be accessed through the g_async_queue_* functions.

  • Constructor Details

    • AsyncQueue

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

  • Method Details

    • getMemoryLayout

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

    • new_

      public static AsyncQueue new_()
      Creates a new asynchronous queue.
      Returns:
      a new GAsyncQueue. Free with g_async_queue_unref()

    • newFull

      public static AsyncQueue newFull()
      Creates a new asynchronous queue and sets up a destroy notify function that is used to free any remaining queue items when the queue is destroyed after the final unref.
      Returns:
      a new GAsyncQueue. Free with g_async_queue_unref()
      Since:
      2.16

    • length

      public int length()

      Returns the length of the queue.

      Actually this function returns the number of data items in the queue minus the number of waiting threads, so a negative value means waiting threads, and a positive value means available entries in the queue. A return value of 0 could mean n entries in the queue and n threads waiting. This can happen due to locking of the queue or due to scheduling.

      Returns:
      the length of the this AsyncQueue

    • lengthUnlocked

      public int lengthUnlocked()

      Returns the length of the queue.

      Actually this function returns the number of data items in the queue minus the number of waiting threads, so a negative value means waiting threads, and a positive value means available entries in the queue. A return value of 0 could mean n entries in the queue and n threads waiting. This can happen due to locking of the queue or due to scheduling.

      This function must be called while holding the queue's lock.

      Returns:
      the length of the queue.

    • lock

      public void lock()

      Acquires the queue's lock. If another thread is already holding the lock, this call will block until the lock becomes available.

      Call g_async_queue_unlock() to drop the lock again.

      While holding the lock, you can only call the g_async_queue_*_unlocked() functions on queue. Otherwise, deadlock may occur.

    • pop

      public MemorySegment pop()
      Pops data from the queue. If this AsyncQueue is empty, this function blocks until data becomes available.
      Returns:
      data from the queue

    • popUnlocked

      public MemorySegment popUnlocked()

      Pops data from the queue. If this AsyncQueue is empty, this function blocks until data becomes available.

      This function must be called while holding the queue's lock.

      Returns:
      data from the queue.

    • push

      public void push(MemorySegment data)

      Pushes the data into the queue.

      The data parameter must not be null.

      Parameters:
      data - data to push onto the this AsyncQueue

    • pushFront

      public void pushFront(MemorySegment item)
      Pushes the item into the queue. item must not be null. In contrast to g_async_queue_push(), this function pushes the new item ahead of the items already in the queue, so that it will be the next one to be popped off the queue.
      Parameters:
      item - data to push into the this AsyncQueue
      Since:
      2.46

    • pushFrontUnlocked

      public void pushFrontUnlocked(MemorySegment item)

      Pushes the item into the queue. item must not be null. In contrast to g_async_queue_push_unlocked(), this function pushes the new item ahead of the items already in the queue, so that it will be the next one to be popped off the queue.

      This function must be called while holding the queue's lock.

      Parameters:
      item - data to push into the this AsyncQueue
      Since:
      2.46

    • pushSorted

      public void pushSorted(MemorySegment data, @Nullable CompareDataFunc func)

      Inserts data into this AsyncQueue using func to determine the new position.

      This function requires that the this AsyncQueue is sorted before pushing on new elements, see g_async_queue_sort().

      This function will lock this AsyncQueue before it sorts the queue and unlock it when it is finished.

      For an example of func see g_async_queue_sort().

      Parameters:
      data - the data to push into the this AsyncQueue
      func - the GCompareDataFunc is used to sort this AsyncQueue
      Since:
      2.10

    • pushSortedUnlocked

      public void pushSortedUnlocked(MemorySegment data, @Nullable CompareDataFunc func)

      Inserts data into this AsyncQueue using func to determine the new position.

      The sort function func is passed two elements of the queue. It should return 0 if they are equal, a negative value if the first element should be higher in the this AsyncQueue or a positive value if the first element should be lower in the this AsyncQueue than the second element.

      This function requires that the this AsyncQueue is sorted before pushing on new elements, see g_async_queue_sort().

      This function must be called while holding the queue's lock.

      For an example of func see g_async_queue_sort().

      Parameters:
      data - the data to push into the this AsyncQueue
      func - the GCompareDataFunc is used to sort this AsyncQueue
      Since:
      2.10

    • pushUnlocked

      public void pushUnlocked(MemorySegment data)

      Pushes the data into the queue.

      The data parameter must not be null.

      This function must be called while holding the queue's lock.

      Parameters:
      data - data to push onto the this AsyncQueue

    • ref

      public AsyncQueue ref()
      Increases the reference count of the asynchronous this AsyncQueue by 1. You do not need to hold the lock to call this function.
      Returns:
      the this AsyncQueue that was passed in (since 2.6)

    • refUnlocked

      @Deprecated public void refUnlocked()
      Deprecated.
      Reference counting is done atomically. so g_async_queue_ref() can be used regardless of the queue's lock.
      Increases the reference count of the asynchronous this AsyncQueue by 1.

    • remove

      public boolean remove(MemorySegment item)
      Remove an item from the queue.
      Parameters:
      item - the data to remove from the this AsyncQueue
      Returns:
      true if the item was removed
      Since:
      2.46

    • removeUnlocked

      public boolean removeUnlocked(MemorySegment item)

      Remove an item from the queue.

      This function must be called while holding the queue's lock.

      Parameters:
      item - the data to remove from the this AsyncQueue
      Returns:
      true if the item was removed
      Since:
      2.46

    • sort

      public void sort(@Nullable CompareDataFunc func)

      Sorts this AsyncQueue using func.

      The sort function func is passed two elements of the queue. It should return 0 if they are equal, a negative value if the first element should be higher in the this AsyncQueue or a positive value if the first element should be lower in the this AsyncQueue than the second element.

      This function will lock this AsyncQueue before it sorts the queue and unlock it when it is finished.

      If you were sorting a list of priority numbers to make sure the lowest priority would be at the top of the queue, you could use:

       gint32 id1;
 gint32 id2;

 id1 = GPOINTER_TO_INT (element1);
 id2 = GPOINTER_TO_INT (element2);

 return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1);
      Parameters:
      func - the GCompareDataFunc is used to sort this AsyncQueue
      Since:
      2.10

    • sortUnlocked

      public void sortUnlocked(@Nullable CompareDataFunc func)

      Sorts this AsyncQueue using func.

      The sort function func is passed two elements of the queue. It should return 0 if they are equal, a negative value if the first element should be higher in the this AsyncQueue or a positive value if the first element should be lower in the this AsyncQueue than the second element.

      This function must be called while holding the queue's lock.

      Parameters:
      func - the GCompareDataFunc is used to sort this AsyncQueue
      Since:
      2.10

    • timedPop

      @Deprecated public @Nullable MemorySegment timedPop(TimeVal endTime)
      Deprecated.
      use g_async_queue_timeout_pop().

      Pops data from the queue. If the queue is empty, blocks until endTime or until data becomes available.

      If no data is received before endTime, null is returned.

      To easily calculate endTime, a combination of g_get_real_time() and g_time_val_add() can be used.

      Parameters:
      endTime - a GTimeVal, determining the final time
      Returns:
      data from the queue or null, when no data is received before endTime.

    • timedPopUnlocked

      @Deprecated public @Nullable MemorySegment timedPopUnlocked(TimeVal endTime)
      Deprecated.
      use g_async_queue_timeout_pop_unlocked().

      Pops data from the queue. If the queue is empty, blocks until endTime or until data becomes available.

      If no data is received before endTime, null is returned.

      To easily calculate endTime, a combination of g_get_real_time() and g_time_val_add() can be used.

      This function must be called while holding the queue's lock.

      Parameters:
      endTime - a GTimeVal, determining the final time
      Returns:
      data from the queue or null, when no data is received before endTime.

    • timeoutPop

      public @Nullable MemorySegment timeoutPop(long timeout)

      Pops data from the queue. If the queue is empty, blocks for timeout microseconds, or until data becomes available.

      If no data is received before the timeout, null is returned.

      Parameters:
      timeout - the number of microseconds to wait
      Returns:
      data from the queue or null, when no data is received before the timeout.

    • timeoutPopUnlocked

      public @Nullable MemorySegment timeoutPopUnlocked(long timeout)

      Pops data from the queue. If the queue is empty, blocks for timeout microseconds, or until data becomes available.

      If no data is received before the timeout, null is returned.

      This function must be called while holding the queue's lock.

      Parameters:
      timeout - the number of microseconds to wait
      Returns:
      data from the queue or null, when no data is received before the timeout.

    • tryPop

      public @Nullable MemorySegment tryPop()
      Tries to pop data from the queue. If no data is available, null is returned.
      Returns:
      data from the queue or null, when no data is available immediately.

    • tryPopUnlocked

      public @Nullable MemorySegment tryPopUnlocked()

      Tries to pop data from the queue. If no data is available, null is returned.

      This function must be called while holding the queue's lock.

      Returns:
      data from the queue or null, when no data is available immediately.

    • unlock

      public void unlock()

      Releases the queue's lock.

      Calling this function when you have not acquired the with g_async_queue_lock() leads to undefined behaviour.

    • unref

      public void unref()

      Decreases the reference count of the asynchronous this AsyncQueue by 1.

      If the reference count went to 0, the this AsyncQueue will be destroyed and the memory allocated will be freed. So you are not allowed to use the this AsyncQueue afterwards, as it might have disappeared. You do not need to hold the lock to call this function.

    • unrefAndUnlock

      @Deprecated public void unrefAndUnlock()
      Deprecated.
      Reference counting is done atomically. so g_async_queue_unref() can be used regardless of the queue's lock.
      Decreases the reference count of the asynchronous this AsyncQueue by 1 and releases the lock. This function must be called while holding the queue's lock. If the reference count went to 0, the this AsyncQueue will be destroyed and the memory allocated will be freed.