luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-08-20 23:58:54 +02:00
Code Issues Packages Projects Releases Wiki Activity

GThreadPool: cosmetic cleanups

Browse Source 
Mostly documentation and formatting trivial, but also add
boolean return types to GError taking functions.
This commit is contained in:
Matthias Clasen
2011-10-01 18:20:27 -04:00
parent 81e161edf2
commit b17b02da79
2 changed files with 428 additions and 398 deletions
Download Patch File Download Diff File Expand all files Collapse all files

243
glib/gthreadpool.c
View File

@@ -37,10 +37,7 @@
* SECTION:thread_pools
* @title: Thread Pools
* @short_description: pools of threads to execute work concurrently
* @see_also: <para> <variablelist> <varlistentry>
* <term>#GThread</term> <listitem><para>GLib thread
* system.</para></listitem> </varlistentry> </variablelist>
* </para>
* @see_also: #GThread
*
* Sometimes you wish to asynchronously fork out the execution of work
* and continue working in your own thread. If that will happen often,
@@ -53,11 +50,11 @@
* advantage is, that the threads can be shared between the different
* subsystems of your program, when they are using GLib.
*
* To create a new thread pool, you use g_thread_pool_new(). It is
* destroyed by g_thread_pool_free().
* To create a new thread pool, you use g_thread_pool_new().
* It is destroyed by g_thread_pool_free().
*
* If you want to execute a certain task within a thread pool, you call
* g_thread_pool_push().
* If you want to execute a certain task within a thread pool,
* you call g_thread_pool_push().
*
* To get the current number of running threads you call
* g_thread_pool_get_num_threads(). To get the number of still
@@ -71,7 +68,7 @@
* controlled by g_thread_pool_get_max_unused_threads() and
* g_thread_pool_set_max_unused_threads(). All currently unused threads
* can be stopped by calling g_thread_pool_stop_unused_threads().
**/
*/
#define DEBUG_MSG(x)
/* #define DEBUG_MSG(args) g_printerr args ; g_printerr ("\n"); */
@@ -85,9 +82,9 @@ typedef struct _GRealThreadPool GRealThreadPool;
* @exclusive: are all threads exclusive to this pool
*
* The #GThreadPool struct represents a thread pool. It has three
* public read-only members, but the underlying struct is bigger, so
* you must not copy this struct.
**/
* public read-only members, but the underlying struct is bigger,
* so you must not copy this struct.
*/
struct _GRealThreadPool
{
GThreadPool pool;
@@ -104,7 +101,8 @@ struct _GRealThreadPool
/* The following is just an address to mark the wakeup order for a
* thread, it could be any address (as long, as it isn't a valid
* GThreadPool address) */
* GThreadPool address)
*/
static const gpointer wakeup_thread_marker = (gpointer) &g_thread_pool_new;
static gint wakeup_thread_serial = 0;
@@ -119,7 +117,7 @@ static void g_thread_pool_queue_push_unlocked (GRealThreadPool *poo
gpointer data);
static void g_thread_pool_free_internal (GRealThreadPool *pool);
static gpointer g_thread_pool_thread_proxy (gpointer data);
static void g_thread_pool_start_thread (GRealThreadPool *pool,
static gboolean g_thread_pool_start_thread (GRealThreadPool *pool,
GError **error);
static void g_thread_pool_wakeup_and_stop_all (GRealThreadPool *pool);
static GRealThreadPool* g_thread_pool_wait_for_new_pool (void);
@@ -201,7 +199,8 @@ g_thread_pool_wait_for_new_pool (void)
/* If a wakeup marker has been relayed, this thread
* will get out of the way for 100 microseconds to
* avoid receiving this marker again. */
* avoid receiving this marker again.
*/
g_usleep (100);
}
}
@@ -296,8 +295,7 @@ g_thread_pool_thread_proxy (gpointer data)
pool = data;
DEBUG_MSG (("thread %p started for pool %p.",
g_thread_self (), pool));
DEBUG_MSG (("thread %p started for pool %p.", g_thread_self (), pool));
g_async_queue_lock (pool->queue);
@@ -310,8 +308,8 @@ g_thread_pool_thread_proxy (gpointer data)
{
if (pool->running || !pool->immediate)
{
/* A task was received and the thread pool is active, so
* execute the function.
/* A task was received and the thread pool is active,
* so execute the function.
*/
g_async_queue_unlock (pool->queue);
DEBUG_MSG (("thread %p in pool %p calling func.",
@@ -322,9 +320,7 @@ g_thread_pool_thread_proxy (gpointer data)
}
else
{
/* No task was received, so this thread goes to the global
* pool.
*/
/* No task was received, so this thread goes to the global pool. */
gboolean free_pool = FALSE;
DEBUG_MSG (("thread %p leaving pool %p for global pool.",
@@ -384,8 +380,8 @@ g_thread_pool_thread_proxy (gpointer data)
g_thread_self (), pool));
/* pool->num_threads++ is not done here, but in
* g_thread_pool_start_thread to make the new started thread
* known to the pool, before itself can do it.
* g_thread_pool_start_thread to make the new started
* thread known to the pool before itself can do it.
*/
}
}
@@ -393,7 +389,7 @@ g_thread_pool_thread_proxy (gpointer data)
return NULL;
}
static void
static gboolean
g_thread_pool_start_thread (GRealThreadPool *pool,
GError **error)
{
@@ -401,7 +397,7 @@ g_thread_pool_start_thread (GRealThreadPool *pool,
if (pool->num_threads >= pool->max_threads && pool->max_threads != -1)
/* Enough threads are already running */
return;
return TRUE;
g_async_queue_lock (unused_thread_queue);
@@ -416,13 +412,12 @@ g_thread_pool_start_thread (GRealThreadPool *pool,
if (!success)
{
GError *local_error = NULL;
/* No thread was found, we have to start a new one */
g_thread_create (g_thread_pool_thread_proxy, pool, FALSE, &local_error);
if (local_error)
/* No thread was found, we have to start a new one */
if (!g_thread_create (g_thread_pool_thread_proxy, pool, FALSE, &local_error))
{
g_propagate_error (error, local_error);
return;
return FALSE;
}
}
@@ -430,6 +425,8 @@ g_thread_pool_start_thread (GRealThreadPool *pool,
* here and not there
*/
pool->num_threads++;
return TRUE;
}
/**
@@ -437,10 +434,10 @@ g_thread_pool_start_thread (GRealThreadPool *pool,
* @func: a function to execute in the threads of the new thread pool
* @user_data: user data that is handed over to @func every time it
* is called
* @max_threads: the maximal number of threads to execute concurrently in
* the new thread pool, -1 means no limit
* @max_threads: the maximal number of threads to execute concurrently
* in the new thread pool, -1 means no limit
* @exclusive: should this thread pool be exclusive?
* @error: return location for error
* @error: return location for error, or %NULL
*
* This function creates a new thread pool.
*
@@ -448,25 +445,25 @@ g_thread_pool_start_thread (GRealThreadPool *pool,
* created or an unused one is reused. At most @max_threads threads
* are running concurrently for this thread pool. @max_threads = -1
* allows unlimited threads to be created for this thread pool. The
* newly created or reused thread now executes the function @func with
* the two arguments. The first one is the parameter to
* newly created or reused thread now executes the function @func
* with the two arguments. The first one is the parameter to
* g_thread_pool_push() and the second one is @user_data.
*
* The parameter @exclusive determines, whether the thread pool owns
* all threads exclusive or whether the threads are shared
* globally. If @exclusive is %TRUE, @max_threads threads are started
* immediately and they will run exclusively for this thread pool until
* it is destroyed by g_thread_pool_free(). If @exclusive is %FALSE,
* threads are created, when needed and shared between all
* non-exclusive thread pools. This implies that @max_threads may not
* be -1 for exclusive thread pools.
* The parameter @exclusive determines whether the thread pool owns
* all threads exclusive or shares them with other thread pools.
* If @exclusive is %TRUE, @max_threads threads are started
* immediately and they will run exclusively for this thread pool
* until it is destroyed by g_thread_pool_free(). If @exclusive is
* %FALSE, threads are created when needed and shared between all
* non-exclusive thread pools. This implies that @max_threads may
* not be -1 for exclusive thread pools.
*
* @error can be %NULL to ignore errors, or non-%NULL to report
* errors. An error can only occur when @exclusive is set to %TRUE and
* not all @max_threads threads could be created.
* errors. An error can only occur when @exclusive is set to %TRUE
* and not all @max_threads threads could be created.
*
* Return value: the new #GThreadPool
**/
*/
GThreadPool *
g_thread_pool_new (GFunc func,
gpointer user_data,
@@ -507,8 +504,8 @@ g_thread_pool_new (GFunc func,
while (retval->num_threads < retval->max_threads)
{
GError *local_error = NULL;
g_thread_pool_start_thread (retval, &local_error);
if (local_error)
if (!g_thread_pool_start_thread (retval, &local_error))
{
g_propagate_error (error, local_error);
break;
@@ -525,7 +522,7 @@ g_thread_pool_new (GFunc func,
* g_thread_pool_push:
* @pool: a #GThreadPool
* @data: a new task for @pool
* @error: return location for error
* @error: return location for error, or %NULL
*
* Inserts @data into the list of tasks to be executed by @pool. When
* the number of currently running threads is lower than the maximal
@@ -536,43 +533,63 @@ g_thread_pool_new (GFunc func,
*
* @error can be %NULL to ignore errors, or non-%NULL to report
* errors. An error can only occur when a new thread couldn't be
* created. In that case @data is simply appended to the queue of work
* to do.
**/
void
* created. In that case @data is simply appended to the queue of
* work to do.
*
* Before version 2.32, this function did not return a success status.
*
* Return value: %TRUE on success, %FALSE if an error occurred
*/
gboolean
g_thread_pool_push (GThreadPool *pool,
gpointer data,
GError **error)
{
GRealThreadPool *real;
gboolean result;
real = (GRealThreadPool*) pool;
g_return_if_fail (real);
g_return_if_fail (real->running);
g_return_val_if_fail (real, FALSE);
g_return_val_if_fail (real->running, FALSE);
result = TRUE;
g_async_queue_lock (real->queue);
if (g_async_queue_length_unlocked (real->queue) >= 0)
{
/* No thread is waiting in the queue */
g_thread_pool_start_thread (real, error);
GError *local_error = NULL;
if (!g_thread_pool_start_thread (real, &local_error))
{
g_propagate_error (error, local_error);
result = FALSE;
}
}
g_thread_pool_queue_push_unlocked (real, data);
g_async_queue_unlock (real->queue);
return result;
}
/**
* g_thread_pool_set_max_threads:
* @pool: a #GThreadPool
* @max_threads: a new maximal number of threads for @pool
* @error: return location for error
* @max_threads: a new maximal number of threads for @pool,
* or -1 for unlimited
* @error: return location for error, or %NULL
*
* Sets the maximal allowed number of threads for @pool. A value of -1
* means, that the maximal number of threads is unlimited.
* Sets the maximal allowed number of threads for @pool.
* A value of -1 means that the maximal number of threads
* is unlimited. If @pool is an exclusive thread pool, setting
* the maximal number of threads to -1 is not allowed.
*
* Setting @max_threads to 0 means stopping all work for @pool. It is
* effectively frozen until @max_threads is set to a non-zero value
* again.
* Setting @max_threads to 0 means stopping all work for @pool.
* It is effectively frozen until @max_threads is set to a non-zero
* value again.
*
* A thread is never terminated while calling @func, as supplied by
* g_thread_pool_new(). Instead the maximal number of threads only
@@ -583,21 +600,28 @@ g_thread_pool_push (GThreadPool *pool,
* @error can be %NULL to ignore errors, or non-%NULL to report
* errors. An error can only occur when a new thread couldn't be
* created.
**/
void
*
* Before version 2.32, this function did not return a success status.
*
* Return value: %TRUE on success, %FALSE if an error occurred
*/
gboolean
g_thread_pool_set_max_threads (GThreadPool *pool,
gint max_threads,
GError **error)
{
GRealThreadPool *real;
gint to_start;
gboolean result;
real = (GRealThreadPool*) pool;
g_return_if_fail (real);
g_return_if_fail (real->running);
g_return_if_fail (!real->pool.exclusive || max_threads != -1);
g_return_if_fail (max_threads >= -1);
g_return_val_if_fail (real, FALSE);
g_return_val_if_fail (real->running, FALSE);
g_return_val_if_fail (!real->pool.exclusive || max_threads != -1, FALSE);
g_return_val_if_fail (max_threads >= -1, FALSE);
result = TRUE;
g_async_queue_lock (real->queue);
@@ -612,15 +636,17 @@ g_thread_pool_set_max_threads (GThreadPool *pool,
{
GError *local_error = NULL;
g_thread_pool_start_thread (real, &local_error);
if (local_error)
if (!g_thread_pool_start_thread (real, &local_error))
{
g_propagate_error (error, local_error);
result = FALSE;
break;
}
}
g_async_queue_unlock (real->queue);
return result;
}
/**
@@ -630,7 +656,7 @@ g_thread_pool_set_max_threads (GThreadPool *pool,
* Returns the maximal number of threads for @pool.
*
* Return value: the maximal number of threads
**/
*/
gint
g_thread_pool_get_max_threads (GThreadPool *pool)
{
@@ -656,7 +682,7 @@ g_thread_pool_get_max_threads (GThreadPool *pool)
* Returns the number of threads currently running in @pool.
*
* Return value: the number of threads currently running
**/
*/
guint
g_thread_pool_get_num_threads (GThreadPool *pool)
{
@@ -682,7 +708,7 @@ g_thread_pool_get_num_threads (GThreadPool *pool)
* Returns the number of tasks still unprocessed in @pool.
*
* Return value: the number of unprocessed tasks
**/
*/
guint
g_thread_pool_unprocessed (GThreadPool *pool)
{
@@ -707,18 +733,19 @@ g_thread_pool_unprocessed (GThreadPool *pool)
*
* Frees all resources allocated for @pool.
*
* If @immediate is %TRUE, no new task is processed for
* @pool. Otherwise @pool is not freed before the last task is
* processed. Note however, that no thread of this pool is
* interrupted, while processing a task. Instead at least all still
* running threads can finish their tasks before the @pool is freed.
* If @immediate is %TRUE, no new task is processed for @pool.
* Otherwise @pool is not freed before the last task is processed.
* Note however, that no thread of this pool is interrupted, while
* processing a task. Instead at least all still running threads
* can finish their tasks before the @pool is freed.
*
* If @wait_ is %TRUE, the functions does not return before all tasks
* to be processed (dependent on @immediate, whether all or only the
* currently running) are ready. Otherwise the function returns immediately.
* If @wait_ is %TRUE, the functions does not return before all
* tasks to be processed (dependent on @immediate, whether all
* or only the currently running) are ready. Otherwise the function
* returns immediately.
*
* After calling this function @pool must not be used anymore.
**/
*/
void
g_thread_pool_free (GThreadPool *pool,
gboolean immediate,
@@ -808,10 +835,10 @@ g_thread_pool_wakeup_and_stop_all (GRealThreadPool* pool)
* g_thread_pool_set_max_unused_threads:
* @max_threads: maximal number of unused threads
*
* Sets the maximal number of unused threads to @max_threads. If
* @max_threads is -1, no limit is imposed on the number of unused
* threads.
**/
* Sets the maximal number of unused threads to @max_threads.
* If @max_threads is -1, no limit is imposed on the number
* of unused threads.
*/
void
g_thread_pool_set_max_unused_threads (gint max_threads)
{
@@ -847,7 +874,7 @@ g_thread_pool_set_max_unused_threads (gint max_threads)
* Returns the maximal allowed number of unused threads.
*
* Return value: the maximal number of unused threads
**/
*/
gint
g_thread_pool_get_max_unused_threads (void)
{
@@ -860,7 +887,7 @@ g_thread_pool_get_max_unused_threads (void)
* Returns the number of currently unused threads.
*
* Return value: the number of currently unused threads
**/
*/
guint
g_thread_pool_get_num_unused_threads (void)
{
@@ -873,7 +900,7 @@ g_thread_pool_get_num_unused_threads (void)
* Stops all currently unused threads. This does not change the
* maximal number of unused threads. This function can be used to
* regularly stop all unused threads e.g. from g_timeout_add().
**/
*/
void
g_thread_pool_stop_unused_threads (void)
{
@@ -894,7 +921,7 @@ g_thread_pool_stop_unused_threads (void)
* a negative value if the first task should be processed before
* the second or a positive value if the second task should be
* processed first.
* @user_data: user data passed to @func.
* @user_data: user data passed to @func
*
* Sets the function used to sort the list of tasks. This allows the
* tasks to be processed by a priority determined by @func, and not
@@ -907,7 +934,7 @@ g_thread_pool_stop_unused_threads (void)
* created.
*
* Since: 2.10
**/
*/
void
g_thread_pool_set_sort_function (GThreadPool *pool,
GCompareDataFunc func,
@@ -935,14 +962,14 @@ g_thread_pool_set_sort_function (GThreadPool *pool,
/**
* g_thread_pool_set_max_idle_time:
* @interval: the maximum @interval (1/1000ths of a second) a thread
* can be idle.
* @interval: the maximum @interval (in milliseconds)
* a thread can be idle
*
* This function will set the maximum @interval that a thread waiting
* in the pool for new tasks can be idle for before being
* stopped. This function is similar to calling
* g_thread_pool_stop_unused_threads() on a regular timeout, except,
* this is done on a per thread basis.
* This function will set the maximum @interval that a thread
* waiting in the pool for new tasks can be idle for before
* being stopped. This function is similar to calling
* g_thread_pool_stop_unused_threads() on a regular timeout,
* except this is done on a per thread basis.
*
* By setting @interval to 0, idle threads will not be stopped.
*
@@ -950,7 +977,7 @@ g_thread_pool_set_sort_function (GThreadPool *pool,
* @interval.
*
* Since: 2.10
**/
*/
void
g_thread_pool_set_max_idle_time (guint interval)
{
@@ -978,17 +1005,19 @@ g_thread_pool_set_max_idle_time (guint interval)
/**
* g_thread_pool_get_max_idle_time:
*
* This function will return the maximum @interval that a thread will
* wait in the thread pool for new tasks before being stopped.
* This function will return the maximum @interval that a
* thread will wait in the thread pool for new tasks before
* being stopped.
*
* If this function returns 0, threads waiting in the thread pool for
* new work are not stopped.
* If this function returns 0, threads waiting in the thread
* pool for new work are not stopped.
*
* Return value: the maximum @interval to wait for new tasks in the
* thread pool before stopping the thread (1/1000ths of a second).
* Return value: the maximum @interval (milliseconds) to wait
* for new tasks in the thread pool before stopping the
* thread
*
* Since: 2.10
**/
*/
guint
g_thread_pool_get_max_idle_time (void)
{

19
glib/gthreadpool.h
View File

@@ -52,25 +52,26 @@ GThreadPool* g_thread_pool_new (GFunc func,
gint max_threads,
gboolean exclusive,
GError **error);
void g_thread_pool_push (GThreadPool *pool,
void g_thread_pool_free (GThreadPool *pool,
gboolean immediate,
gboolean wait_);
gboolean g_thread_pool_push (GThreadPool *pool,
gpointer data,
GError **error);
void g_thread_pool_set_max_threads (GThreadPool *pool,
guint g_thread_pool_unprocessed (GThreadPool *pool);
void g_thread_pool_set_sort_function (GThreadPool *pool,
GCompareDataFunc func,
gpointer user_data);
gboolean g_thread_pool_set_max_threads (GThreadPool *pool,
gint max_threads,
GError **error);
gint g_thread_pool_get_max_threads (GThreadPool *pool);
guint g_thread_pool_get_num_threads (GThreadPool *pool);
guint g_thread_pool_unprocessed (GThreadPool *pool);
void g_thread_pool_free (GThreadPool *pool,
gboolean immediate,
gboolean wait_);
void g_thread_pool_set_max_unused_threads (gint max_threads);
gint g_thread_pool_get_max_unused_threads (void);
guint g_thread_pool_get_num_unused_threads (void);
void g_thread_pool_stop_unused_threads (void);
void g_thread_pool_set_sort_function (GThreadPool *pool,
GCompareDataFunc func,
gpointer user_data);
void g_thread_pool_set_max_idle_time (guint interval);
guint g_thread_pool_get_max_idle_time (void);