Package org.gnome.glib

Class AsyncQueue

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.gnome.glib.AsyncQueue

All Implemented Interfaces:

Proxy

@Generated("io.github.jwharm.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 Summary

Constructors

Constructor	Description
AsyncQueue(MemorySegment address)	Create a AsyncQueue proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
int	length()	Returns the length of the queue.
int	lengthUnlocked()	Returns the length of the queue.
void	lock()	Acquires the this AsyncQueue's lock.
static AsyncQueue	new_()	Creates a new asynchronous queue.
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.
MemorySegment	pop()	Pops data from the this AsyncQueue.
MemorySegment	popUnlocked()	Pops data from the this AsyncQueue.
void	push(MemorySegment data)	Pushes the data into the this AsyncQueue.
void	pushFront(MemorySegment item)	Pushes the item into the this AsyncQueue.
void	pushFrontUnlocked(MemorySegment item)	Pushes the item into the this AsyncQueue.
void	pushSorted(MemorySegment data, CompareDataFunc func)	Inserts data into this AsyncQueue using func to determine the new position.
void	pushSortedUnlocked(@Nullable MemorySegment data, CompareDataFunc func)	Inserts data into this AsyncQueue using func to determine the new position.
void	pushUnlocked(MemorySegment data)	Pushes the data into the this AsyncQueue.
AsyncQueue	ref()	Increases the reference count of the asynchronous this AsyncQueue by 1.
void	refUnlocked()	Deprecated. Reference counting is done atomically.
boolean	remove(MemorySegment item)	Remove an item from the queue.
boolean	removeUnlocked(@Nullable MemorySegment item)	Remove an item from the queue.
void	sort(CompareDataFunc func)	Sorts this AsyncQueue using func.
void	sortUnlocked(CompareDataFunc func)	Sorts this AsyncQueue using func.
MemorySegment	timedPop(TimeVal endTime)	Deprecated. use g_async_queue_timeout_pop().
MemorySegment	timedPopUnlocked(TimeVal endTime)	Deprecated. use g_async_queue_timeout_pop_unlocked().
MemorySegment	timeoutPop(long timeout)	Pops data from the this AsyncQueue.
MemorySegment	timeoutPopUnlocked(long timeout)	Pops data from the this AsyncQueue.
MemorySegment	tryPop()	Tries to pop data from the this AsyncQueue.
MemorySegment	tryPopUnlocked()	Tries to pop data from the this AsyncQueue.
void	unlock()	Releases the queue's lock.
void	unref()	Decreases the reference count of the asynchronous this AsyncQueue by 1.
void	unrefAndUnlock()	Deprecated. Reference counting is done atomically.

Methods inherited from class io.github.jwharm.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

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

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

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 this AsyncQueue. 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 this AsyncQueue. 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 this AsyncQueue's lock.

Returns:

the length of the this AsyncQueue.

lock

public void lock()

Acquires the this AsyncQueue'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 this AsyncQueue. Otherwise, deadlock may occur.

pop

public MemorySegment pop()

Pops data from the this AsyncQueue. 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 this AsyncQueue. If this AsyncQueue is empty, this function blocks until data becomes available.

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

Returns:

data from the queue.

push

public void push(MemorySegment data)

Pushes the data into the this AsyncQueue.

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 this AsyncQueue. 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

pushFrontUnlocked

public void pushFrontUnlocked(MemorySegment item)

Pushes the item into the this AsyncQueue. 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 this AsyncQueue's lock.

Parameters:

item - data to push into the this AsyncQueue

pushSorted

public void pushSorted(MemorySegment data,
 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

pushSortedUnlocked

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

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

The sort function func is passed two elements of the this AsyncQueue. 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 this AsyncQueue'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

pushUnlocked

public void pushUnlocked(MemorySegment data)

Pushes the data into the this AsyncQueue.

The data parameter must not be null.

This function must be called while holding the this AsyncQueue'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 this AsyncQueue'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

removeUnlocked

public boolean removeUnlocked(@Nullable
 @Nullable MemorySegment item)

Remove an item from the queue.

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

Parameters:

item - the data to remove from the this AsyncQueue

Returns:

true if the item was removed

sort

public void sort(CompareDataFunc func)

Sorts this AsyncQueue using func.

The sort function func is passed two elements of the this AsyncQueue. 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

sortUnlocked

public void sortUnlocked(CompareDataFunc func)

Sorts this AsyncQueue using func.

The sort function func is passed two elements of the this AsyncQueue. 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 this AsyncQueue's lock.

Parameters:

func - the GCompareDataFunc is used to sort this AsyncQueue

timedPop

@Deprecated
public MemorySegment timedPop(TimeVal endTime)

Deprecated.

use g_async_queue_timeout_pop().

Pops data from the this AsyncQueue. 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 MemorySegment timedPopUnlocked(TimeVal endTime)

Deprecated.

use g_async_queue_timeout_pop_unlocked().

Pops data from the this AsyncQueue. 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 this AsyncQueue'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 MemorySegment timeoutPop(long timeout)

Pops data from the this AsyncQueue. 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 MemorySegment timeoutPopUnlocked(long timeout)

Pops data from the this AsyncQueue. 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 this AsyncQueue'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 MemorySegment tryPop()

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

Returns:

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

tryPopUnlocked

public MemorySegment tryPopUnlocked()

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

This function must be called while holding the this AsyncQueue'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 this AsyncQueue'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 this AsyncQueue's lock. If the reference count went to 0, the this AsyncQueue will be destroyed and the memory allocated will be freed.