Top | ![]() |
![]() |
![]() |
![]() |
gs-worker-threadgs-worker-thread — A worker thread which executes queued GTasks until stopped |
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
) when executing that task.ioprio_set()
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.
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.
Since: 42
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.
self |
||
priority |
priority to queue the task at, typically G_PRIORITY_DEFAULT. |
[default G_PRIORITY_DEFAULT] |
work_func |
function to run the task. |
[not nullable] |
task |
the GTask containing context data to
pass to |
[transfer full][not nullable] |
Since: 42
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 } |
Since: 42
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.
self |
||
cancellable |
a GCancellable, or |
[nullable] |
callback |
callback for once the asynchronous operation is complete |
|
user_data |
data to pass to |
Since: 42
gboolean gs_worker_thread_shutdown_finish (GsWorkerThread *self
,GAsyncResult *result
,GError **error
);
Finish an asynchronous shutdown operation started with
gs_worker_thread_shutdown_async()
;
Since: 42