class: GThreadPool

[34:7] extends: object

The GThreadPool struct represents a thread pool. A thread pool is useful when you wish to asynchronously fork out the execution of work and continue working in your own thread. If that will happen often, the overhead of starting and destroying a thread each time might be too high. In such cases reusing already started threads seems like a good idea. And it indeed is, but implementing this can be tedious and error-prone. Therefore GLib provides thread pools for your convenience. An added 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 [func@GLib.ThreadPool.new]. It is destroyed by [method@GLib.ThreadPool.free]. If you want to execute a certain task within a thread pool, use [method@GLib.ThreadPool.push]. To get the current number of running threads you call [method@GLib.ThreadPool.get_num_threads]. To get the number of still unprocessed tasks you call [method@GLib.ThreadPool.unprocessed]. To control the maximum number of threads for a thread pool, you use [method@GLib.ThreadPool.get_max_threads]. and [method@GLib.ThreadPool.set_max_threads]. Finally you can control the number of unused threads, that are kept alive by GLib for future use. The current number can be fetched with [func@GLib.ThreadPool.get_num_unused_threads]. The maximum number can be controlled by [func@GLib.ThreadPool.get_max_unused_threads] and [func@GLib.ThreadPool.set_max_unused_threads]. All currently unused threads can be stopped by calling [func@GLib.ThreadPool.stop_unused_threads].

Members

handleObj
lib
retainedCallbacks
signalHandlerNames
signalSetterHandlers

Methods

GThreadPool (Handle = null)

Creates a new ThreadPool by wrapping a native handle or another wrapper.
- @p Handle is the native handle or another wrapper whose handle to adopt.
toNativeHandle (Source)

Normalizes a constructor argument into a raw pointer carrier. Accepts a raw NativeHandle, a raw NativeBuffer returned from fn.call(...), another generated wrapper exposing handle(), or null. Returns null when the argument carries no pointer.
- @p Source is the raw handle, raw buffer, wrapper, or null.
- @r A raw pointer carrier or null when no pointer is present.
getLib ()

Returns the opened native library for this generated wrapper.
- @r The opened native library.
handle ()

Returns the wrapped NativeHandle.
- @r The wrapped NativeHandle.
isNull ()

Returns true when the wrapped handle is null.
- @r A bool.
describe ()

Returns a small string for debugging generated wrappers.
- @r A string.
free (bool immediate, bool wait_)

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 @wait_ is %TRUE, this function does not return before all tasks to be processed (dependent on @immediate, whether all or only the currently running) are ready. Otherwise this function returns immediately. After calling this function @pool must not be used anymore.
- @p immediate is should @pool shut down immediately?.
- @p wait_ is should the function wait for all tasks to be finished?.
- @r None.
get_max_threads ()

Returns the maximal number of threads for @pool.
- @r the maximal number of threads.
get_num_threads ()

Returns the number of threads currently running in @pool.
- @r the number of threads currently running.
move_to_front (data)

Moves the item to the front of the queue of unprocessed items, so that it will be processed next.
- @p data is an unprocessed item in the pool.
- @r %TRUE if the item was found and moved.
push (data)

Inserts @data into the list of tasks to be executed by @pool. When the number of currently running threads is lower than the maximal allowed number of threads, a new thread is started (or reused) with the properties given to g_thread_pool_new(). Otherwise, @data stays in the queue until a thread in this pool finishes its previous task and processes @data. @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. Before version 2.32, this function did not return a success status.
- @p data is a new task for @pool.
- @r %TRUE on success, %FALSE if an error occurred.
set_max_threads (int max_threads)

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. A thread is never terminated while calling @func, as supplied by g_thread_pool_new(). Instead the maximal number of threads only has effect for the allocation of new threads in g_thread_pool_push(). A new thread is allocated, whenever the number of currently running threads in
- @pool is smaller than the maximal number. @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. Before version 2.32, this function did not return a success status.
- @p max_threads is a new maximal number of threads for @pool, or -1 for unlimited.
- @r %TRUE on success, %FALSE if an error occurred.
set_sort_function (user_data)

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 just in the order in which they were added to the pool. Note, if the maximum number of threads is more than 1, the order that threads are executed cannot be guaranteed 100%. Threads are scheduled by the operating system and are executed at random. It cannot be assumed that threads are executed in the order they are created.
- @p func is the #GCompareDataFunc used to sort the list of tasks. This function is passed two tasks. It should return 0 if the order in which they are handled does not matter, 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..
- @p user_data is user data passed to @func.
- @r None.
unprocessed ()

Returns the number of tasks still unprocessed in @pool.
- @r the number of unprocessed tasks.