Package org.gnome.glib

Class AsyncQueue

java.lang.Object

org.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 queue'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 queue. If this AsyncQueue is empty, this function blocks until data becomes available.
MemorySegment	popUnlocked()	Pops data from the queue. If this AsyncQueue is empty, this function blocks until data becomes available.
void	push(MemorySegment data)	Pushes the data into the queue.
void	pushFront(MemorySegment item)	Pushes the item into the queue. item must not be null.
void	pushFrontUnlocked(MemorySegment item)	Pushes the item into the queue. item must not be null.
void	pushSorted(MemorySegment data, @Nullable CompareDataFunc func)	Inserts data into this AsyncQueue using func to determine the new position.
void	pushSortedUnlocked(MemorySegment data, @Nullable CompareDataFunc func)	Inserts data into this AsyncQueue using func to determine the new position.
void	pushUnlocked(MemorySegment data)	Pushes the data into the queue.
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(MemorySegment item)	Remove an item from the queue.
void	sort(@Nullable CompareDataFunc func)	Sorts this AsyncQueue using func.
void	sortUnlocked(@Nullable CompareDataFunc func)	Sorts this AsyncQueue using func.
@Nullable MemorySegment	timedPop(TimeVal endTime)	Deprecated. use g_async_queue_timeout_pop().
@Nullable MemorySegment	timedPopUnlocked(TimeVal endTime)	Deprecated. use g_async_queue_timeout_pop_unlocked().
@Nullable MemorySegment	timeoutPop(long timeout)	Pops data from the queue. If the queue is empty, blocks for timeout microseconds, or until data becomes available.
@Nullable MemorySegment	timeoutPopUnlocked(long timeout)	Pops data from the queue. If the queue is empty, blocks for timeout microseconds, or until data becomes available.
@Nullable MemorySegment	tryPop()	Tries to pop data from the queue. If no data is available, null is returned.
@Nullable MemorySegment	tryPopUnlocked()	Tries to pop data from the queue. If no data is available, null is returned.
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 org.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()

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.