glib.AsyncQueue.AsyncQueue Class Reference

List of all members.

Detailed Description

Description Often you need to communicate between different threads.

In general it's safer not to do this by shared memory, but by explicit message passing. These messages only make sense asynchronously for multi-threaded applications though, as a synchronous operation could as well be done in the same thread. Asynchronous queues are an exception from most other GLib data structures, as they can be used simultaneously from multiple threads without explicit locking and they bring their own builtin reference counting. This is because the nature of an asynchronous queue is that it will always be used by at least 2 concurrent threads. For using an asynchronous queue you first have to create one with g_async_queue_new(). A newly-created queue will get the reference count 1. Whenever another thread is creating a new reference of (that is, pointer to) the queue, it has to increase the reference count (using g_async_queue_ref()). Also, before removing this reference, the reference count has to be decreased (using g_async_queue_unref()). After that the queue might no longer exist so you must not access it after that point. A thread, which wants to send a message to that queue simply calls g_async_queue_push() to push the message to the queue. A thread, which is expecting messages from an asynchronous queue simply calls g_async_queue_pop() for that queue. If no message is available in the queue at that point, the thread is now put to sleep until a message arrives. The message will be removed from the queue and returned. The functions g_async_queue_try_pop() and g_async_queue_timed_pop() can be used to only check for the presence of messages or to only wait a certain time for messages respectively. For almost every function there exist two variants, one that locks the queue and one that doesn't. That way you can hold the queue lock (acquire it with g_async_queue_lock() and release it with g_async_queue_unlock()) over multiple queue accessing instructions. This can be necessary to ensure the integrity of the queue, but should only be used when really necessary, as it can make your life harder if used unwisely. Normally you should only use the locking function variants (those without the suffix _unlocked)


Public Member Functions

GAsyncQueuegetAsyncQueueStruct ()
 this (GAsyncQueue *gAsyncQueue)
 Sets our main struct and passes it to the parent class.
 this ()
 Creates a new asynchronous queue with the initial reference count of 1.
AsyncQueue ref ()
 Increases the reference count of the asynchronous queue by 1.
void unref ()
 Decreases the reference count of the asynchronous queue by 1.
void push (void *data)
 Pushes the data into the queue.
void pushSorted (void *data, GCompareDataFunc func, void *userData)
 Inserts data into queue using func to determine the new position.
void * pop ()
 Pops data from the queue.
void * tryPop ()
 Tries to pop data from the queue.
void * timedPop (GTimeVal *endTime)
 Pops data from the queue.
int length ()
 Returns the length of the queue, negative values mean waiting threads, positive values mean available entries in the queue.
void sort (GCompareDataFunc func, void *userData)
 Sorts queue using func.
void lock ()
 Acquires the queue's lock.
void unlock ()
 Releases the queue's lock.
void refUnlocked ()
 Warning g_async_queue_ref_unlocked is deprecated and should not be used in newly-written code.
void unrefAndUnlock ()
 Warning g_async_queue_unref_and_unlock is deprecated and should not be used in newly-written code.
void pushUnlocked (void *data)
 Pushes the data into the queue.
void pushSortedUnlocked (void *data, GCompareDataFunc func, void *userData)
 Inserts data into queue using func to determine the new position.
void * popUnlocked ()
 Pops data from the queue.
void * tryPopUnlocked ()
 Tries to pop data from the queue.
void * timedPopUnlocked (GTimeVal *endTime)
 Pops data from the queue.
int lengthUnlocked ()
 Returns the length of the queue, negative values mean waiting threads, positive values mean available entries in the queue.
void sortUnlocked (GCompareDataFunc func, void *userData)
 Sorts queue using func.

Protected Member Functions

void * getStruct ()
 the main Gtk struct as a void*

Protected Attributes

GAsyncQueuegAsyncQueue
 the main Gtk struct


Constructor & Destructor Documentation

glib.AsyncQueue.AsyncQueue.this ( GAsyncQueue gAsyncQueue  ) 

Sets our main struct and passes it to the parent class.

glib.AsyncQueue.AsyncQueue.this (  ) 

Creates a new asynchronous queue with the initial reference count of 1.

Returns: the new GAsyncQueue.


Member Function Documentation

GAsyncQueue* glib.AsyncQueue.AsyncQueue.getAsyncQueueStruct (  ) 

void* glib.AsyncQueue.AsyncQueue.getStruct (  )  [protected]

the main Gtk struct as a void*

int glib.AsyncQueue.AsyncQueue.length (  ) 

Returns the length of the queue, negative values mean waiting threads, positive values mean available entries in the queue.

Actually this function returns the number of data items in the queue minus the number of waiting threads. Thus a return value of 0 could mean 'n' entries in the queue and 'n' thread waiting. That can happen due to locking of the queue or due to scheduling. queue: a GAsyncQueue. Returns: the length of the queue.

int glib.AsyncQueue.AsyncQueue.lengthUnlocked (  ) 

Returns the length of the queue, negative values mean waiting threads, positive values mean available entries in the queue.

Actually this function returns the number of data items in the queue minus the number of waiting threads. Thus a return value of 0 could mean 'n' entries in the queue and 'n' thread waiting. That can happen due to locking of the queue or due to scheduling. This function must be called while holding the queue's lock. queue: a GAsyncQueue. Returns: the length of the queue.

void glib.AsyncQueue.AsyncQueue.lock (  ) 

Acquires the queue's lock.

After that you can only call the g_async_queue_*_unlocked() function variants on that queue. Otherwise it will deadlock. queue: a GAsyncQueue.

void* glib.AsyncQueue.AsyncQueue.pop (  ) 

Pops data from the queue.

This function blocks until data become available. queue: a GAsyncQueue. Returns: data from the queue.

void* glib.AsyncQueue.AsyncQueue.popUnlocked (  ) 

Pops data from the queue.

This function blocks until data become available. This function must be called while holding the queue's lock. queue: a GAsyncQueue. Returns: data from the queue.

void glib.AsyncQueue.AsyncQueue.push ( void *  data  ) 

Pushes the data into the queue.

data must not be NULL. queue: a GAsyncQueue. data: data to push into the queue.

void glib.AsyncQueue.AsyncQueue.pushSorted ( void *  data,
GCompareDataFunc  func,
void *  userData 
)

Inserts data into queue using func to determine the new position.

This function requires that the queue is sorted before pushing on new elements. This function will lock queue before it sorts the queue and unlock it when it is finished. For an example of func see g_async_queue_sort(). queue: a GAsyncQueue data: the data to push into the queue func: the GCompareDataFunc is used to sort queue. This function is passed two elements of the queue. The function should return 0 if they are equal, a negative value if the first element should be higher in the queue or a positive value if the first element should be lower in the queue than the second element. user_data: user data passed to func. Since 2.10

void glib.AsyncQueue.AsyncQueue.pushSortedUnlocked ( void *  data,
GCompareDataFunc  func,
void *  userData 
)

Inserts data into queue using func to determine the new position.

This function requires that the queue is sorted before pushing on new elements. This function is called while holding the queue's lock. For an example of func see g_async_queue_sort(). queue: a GAsyncQueue data: the data to push into the queue func: the GCompareDataFunc is used to sort queue. This function is passed two elements of the queue. The function should return 0 if they are equal, a negative value if the first element should be higher in the queue or a positive value if the first element should be lower in the queue than the second element. user_data: user data passed to func. Since 2.10

void glib.AsyncQueue.AsyncQueue.pushUnlocked ( void *  data  ) 

Pushes the data into the queue.

data must not be NULL. This function must be called while holding the queue's lock. queue: a GAsyncQueue. data: data to push into the queue.

AsyncQueue glib.AsyncQueue.AsyncQueue.ref (  ) 

Increases the reference count of the asynchronous queue by 1.

You do not need to hold the lock to call this function. queue: a GAsyncQueue. Returns: the queue that was passed in (since 2.6)

void glib.AsyncQueue.AsyncQueue.refUnlocked (  ) 

Warning g_async_queue_ref_unlocked is deprecated and should not be used in newly-written code.

Increases the reference count of the asynchronous queue by 1. Deprecated: Since 2.8, reference counting is done atomically so g_async_queue_ref() can be used regardless of the queue's lock. queue: a GAsyncQueue.

void glib.AsyncQueue.AsyncQueue.sort ( GCompareDataFunc  func,
void *  userData 
)

Sorts queue using func.

This function will lock queue 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); queue: a GAsyncQueue func: the GCompareDataFunc is used to sort queue. This function is passed two elements of the queue. The function should return 0 if they are equal, a negative value if the first element should be higher in the queue or a positive value if the first element should be lower in the queue than the second element. user_data: user data passed to func Since 2.10

void glib.AsyncQueue.AsyncQueue.sortUnlocked ( GCompareDataFunc  func,
void *  userData 
)

Sorts queue using func.

This function is called while holding the queue's lock. queue: a GAsyncQueue func: the GCompareDataFunc is used to sort queue. This function is passed two elements of the queue. The function should return 0 if they are equal, a negative value if the first element should be higher in the queue or a positive value if the first element should be lower in the queue than the second element. user_data: user data passed to func Since 2.10

void* glib.AsyncQueue.AsyncQueue.timedPop ( GTimeVal endTime  ) 

Pops data from the queue.

If no data is received before end_time, NULL is returned. To easily calculate end_time a combination of g_get_current_time() and g_time_val_add() can be used. queue: a GAsyncQueue. end_time: a GTimeVal, determining the final time. Returns: data from the queue or NULL, when no data is received before end_time.

void* glib.AsyncQueue.AsyncQueue.timedPopUnlocked ( GTimeVal endTime  ) 

Pops data from the queue.

If no data is received before end_time, NULL is returned. This function must be called while holding the queue's lock. To easily calculate end_time a combination of g_get_current_time() and g_time_val_add() can be used. queue: a GAsyncQueue. end_time: a GTimeVal, determining the final time. Returns: data from the queue or NULL, when no data is received before end_time.

void* glib.AsyncQueue.AsyncQueue.tryPop (  ) 

Tries to pop data from the queue.

If no data is available, NULL is returned. queue: a GAsyncQueue. Returns: data from the queue or NULL, when no data is available immediately.

void* glib.AsyncQueue.AsyncQueue.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. queue: a GAsyncQueue. Returns: data from the queue or NULL, when no data is available immediately.

void glib.AsyncQueue.AsyncQueue.unlock (  ) 

Releases the queue's lock.

queue: a GAsyncQueue.

void glib.AsyncQueue.AsyncQueue.unref (  ) 

Decreases the reference count of the asynchronous queue by 1.

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

void glib.AsyncQueue.AsyncQueue.unrefAndUnlock (  ) 

Warning g_async_queue_unref_and_unlock is deprecated and should not be used in newly-written code.

Decreases the reference count of the asynchronous queue 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 queue will be destroyed and the memory allocated will be freed. Deprecated: Since 2.8, reference counting is done atomically so g_async_queue_unref() can be used regardless of the queue's lock. queue: a GAsyncQueue.


Member Data Documentation

GAsyncQueue* glib.AsyncQueue.AsyncQueue.gAsyncQueue [protected]

the main Gtk struct


SourceForge.net Logo DSource.org Logo digitalmars.com Logo