gs-worker-thread: GNOME Software Reference Manual

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

## Functions

GsWorkerThread * | gs_worker_thread_new ()
void | gs_worker_thread_queue ()
gboolean | gs_worker_thread_is_in_worker_context ()
void | gs_worker_thread_shutdown_async ()
gboolean | gs_worker_thread_shutdown_finish ()

## Types and Values

#define | GS_TYPE_WORKER_THREAD
| GsWorkerThread

## 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]
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;