gs-worker-thread

gs-worker-thread — A worker thread which executes queued GTasks until stopped

Functions

Types and Values

Description

GsWorkerThread is a thread-safe wrapper around a GTask queue and a single worker thread which executes tasks on that queue.

Tasks can be added to the queue using gs_worker_thread_queue(). The worker thread (which is created when GsWorkerThread is constructed) will execute them in (priority, queue order) order. Each GTaskThreadFunc is responsible for calling g_task_return_*() on its GTask to complete that task.

The priority passed to gs_worker_thread_queue() will be used to adjust the worker thread’s I/O priority (using ioprio_set()) when executing that task.

It is intended that gs_worker_thread_queue() is an alternative to using g_task_run_in_thread(). g_task_run_in_thread() queues tasks into a single process-wide thread pool, so they are mixed in with other tasks, and it can become hard to ensure the thread pool isn’t overwhelmed and that tasks are executed in the right order.

The worker thread will continue executing tasks until gs_worker_thread_shutdown_async() is called. This must be called before the final reference to the GsWorkerThread is dropped.

Functions

gs_worker_thread_new ()

GsWorkerThread *
gs_worker_thread_new (const gchar *name);

Create and start a new GsWorkerThread.

name will be used to set the thread name and in debug output.

Parameters

name

name for the worker thread.

[not nullable]

Returns

a new GsWorkerThread.

[transfer full]

Since: 42


gs_worker_thread_queue ()

void
gs_worker_thread_queue (GsWorkerThread *self,
                        gint priority,
                        GTaskThreadFunc work_func,
                        GTask *task);

Queue task to be run in the worker thread at the given priority .

This function takes ownership of task .

priority sets the order of the task in the queue, and also affects the I/O priority of the worker thread when the task is executed — high priorities result in a high I/O priority, low priorities result in an idle I/O priority, as per ioprio_set().

When the task is run, work_func will be executed and passed task and the source object, task data and cancellable set on task .

work_func is responsible for calling g_task_return_*() on task once the task is complete.

If a task is cancelled using its GCancellable after it’s queued to the GsWorkerThread, work_func will still be executed. work_func is responsible for checking whether the GCancellable has been cancelled.

It is an error to call this function after gs_worker_thread_shutdown_async() has called.

Parameters

self

a GsWorkerThread

 

priority

priority to queue the task at, typically G_PRIORITY_DEFAULT.

[default G_PRIORITY_DEFAULT]

work_func

function to run the task.

[not nullable][scope async]

task

the GTask containing context data to pass to work_func .

[transfer full][not nullable]

Since: 42


gs_worker_thread_is_in_worker_context ()

gboolean
gs_worker_thread_is_in_worker_context (GsWorkerThread *self);

Returns whether the calling thread is the worker thread.

This is intended to be used as a precondition check to ensure that worker code is not accidentally run from the wrong thread.

1
2
3
4
5
6
7
static void
do_work (MyPlugin *self)
{
  g_assert (gs_worker_thread_is_in_worker_context (self->worker_thread));

  // do some work
}

Parameters

self

a GsWorkerThread

 

Returns

TRUE if running in the worker context, FALSE otherwise

Since: 42


gs_worker_thread_shutdown_async ()

void
gs_worker_thread_shutdown_async (GsWorkerThread *self,
                                 GCancellable *cancellable,
                                 GAsyncReadyCallback callback,
                                 gpointer user_data);

Shut down the worker thread.

The thread will finish processing whatever task it’s currently processing (if any), will return G_IO_ERROR_CANCELLED for all remaining queued tasks, and will then join the main process.

This is a no-op if called subsequently.

Parameters

self

a GsWorkerThread

 

cancellable

a GCancellable, or NULL.

[nullable]

callback

callback for once the asynchronous operation is complete

 

user_data

data to pass to callback

 

Since: 42


gs_worker_thread_shutdown_finish ()

gboolean
gs_worker_thread_shutdown_finish (GsWorkerThread *self,
                                  GAsyncResult *result,
                                  GError **error);

Finish an asynchronous shutdown operation started with gs_worker_thread_shutdown_async();

Parameters

self

a GsWorkerThread

 

result

a GAsyncResult

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE otherwise

Since: 42

Types and Values

GS_TYPE_WORKER_THREAD

#define GS_TYPE_WORKER_THREAD (gs_worker_thread_get_type ())

GsWorkerThread

typedef struct _GsWorkerThread GsWorkerThread;