xtd::threading::thread_pool Class Reference

Inheritance diagram for xtd::threading::thread_pool:

Definition

Provides a pool of threads that can be used to execute tasks, post work items, process asynchronous I/O, wait on behalf of other threads, and process timers.

class core_export_ thread_pool static_

Inheritance

xtd::static_object → xtd::threading::thread_pool

Header

#include <xtd/threading/thread_pool>

Namespace

xtd::threading

Library

xtd.core

Examples

In the following example, the main application thread queues a method named ThreadProc to execute on a thread pool thread, sleeps for one second, and then exits. The ThreadProc method simply displays a message.

#include <xtd/xtd>
 
namespace wait_handle_example {
  class program {
  public:
    static void main() {
      // Queue the task.
      thread_pool::queue_user_work_item({thread_proc});
      console::write_line("Main thread does some work, then sleeps.");
      thread::sleep(1000);
      
      console::write_line("Main thread exits.");
    }
   
  private:
    // This thread procedure performs the task.
    static void thread_proc(any_object state_info) {
      // No state object was passed to queue_user_work_item, so state_info has no value.
      console::write_line("Hello from the thread pool.");
    }
  };
}
 
startup_(wait_handle_example::program::main);
 
// This example produces output similar to the following:
//
// Main thread does some work, then sleeps.
// Hello from the thread pool.
// Main thread exits.

If you comment out the call to the xtd::threading::thread::sleep method, the main thread exits before method runs on the thread pool thread. The thread pool uses background threads, which do not keep the application running if all foreground threads have terminated. (This is a simple example of a race condition.)

Remarks

Many applications create threads that spend a great deal of time in the sleeping state, waiting for an event to occur. Other threads might enter a sleeping state only to be awakened periodically to poll for a change or update status information. The thread pool enables you to use threads more efficiently by providing your application with a pool of worker threads that are managed by the system. Examples of operations that use thread pool threads include the following:

• When you create a xtd::threading::task::task or xtd::threading::task::task < result_t > object to perform some task asynchronously, by default the task is scheduled to run on a thread pool thread.
• Asynchronous timers use the thread pool. Thread pool threads execute callbacks from the xtd::threading::timer class and raise events from the xtd::timers::timer class.
• When you use registered wait handles, a system thread monitors the status of the wait handles. When a wait operation completes, a worker thread from the thread pool executes the corresponding callback function.
• When you call the xtd::threading::thread_pool::queue_user_work_item method to queue a method for execution on a thread pool thread. You do this by passing the method a xtd::threading::wait_callback delegate. The delegate has the signature @verbatom using wait_callback = action<const xtd::any_object&> where state is an object that contains data to be used by the delegate. The actual data can be passed to the delegate by calling the xtd::threading::thread_pool::queue_user_work_item(xtd::threading::wait_callback, const xtd::any_object&) method.

Note

The threads in the managed thread pool are background threads. That is, their xtd::threading::thread::is_background properties are true. This means that a xtd::threading::thread_pool thread will not keep an application running after all foreground threads have exited.

Remarks

You can also queue work items that are not related to a wait operation to the thread pool. To request that a work item be handled by a thread in the thread pool, call the xtd::threading::thread_pool::queue_user_work_item method. This method takes as a parameter a reference to the method or delegate that will be called by the thread selected from the thread pool. There is no way to cancel a work item after it has been queued.

Timer-queue timers and registered wait operations also use the thread pool. Their callback functions are queued to the thread pool.

There is one thread pool per process.The default size of the thread pool for a process depends on several factors, such as the size of the virtual address space. A process can call the xtd::threading::thread_pool::gt_max_threads method to determine the number of threads. The number of threads in the thread pool can be changed by using the xtd::threading::thread_pool::set_max_threads method. Each thread uses the default stack size and runs at the default priority.

The thread pool provides new worker threads or I/O completion threads on demand until it reaches the maximum for each category. When a maximum is reached, the thread pool can create additional threads in that category or wait until some tasks complete. The thread pool creates and destroys worker threads in order to optimize throughput, which is defined as the number of tasks that complete per unit of time. Too few threads might not make optimal use of available resources, whereas too many threads could increase resource contention.

Note

When demand is low, the actual number of thread pool threads can fall below the minimum values.

Remarks

You can use the xtd::threading::thread_pool::get_min_threads method to obtain these minimum values.

Warning

You can use the xtd::threading::thread_pool::set_min_threads method to increase the minimum number of threads. However, unnecessarily increasing these values can cause performance problems. If too many tasks start at the same time, all of them might appear to be slow. In most cases the thread pool will perform better with its own algorithm for allocating threads.

Public Static Methods
static auto	close () -> void
	Close all resources and worker threads.
static auto	get_available_threads (size_t &worker_threads, size_t &completion_port_threads) -> void
	Retrieves the difference between the maximum number of thread pool threads returned by the GetMaxThreads method, and the number currently active.
static auto	get_max_threads (size_t &worker_threads, size_t &completion_port_threads) -> void
	Retrieves the number of requests to the thread pool that can be active concurrently. All requests above that number remain queued until thread pool threads become available.
static auto	get_min_threads (size_t &worker_threads, size_t &completion_port_threads) -> void
	Retrieves the number of idle threads the thread pool maintains in anticipation of new requests. Always 0 for both.
static auto	join_all () -> void
	Join all resources and worker threads.
static auto	join_all (int32 milliseconds_timeout) -> bool
	Join all resources and worker threads.
static auto	join_all (const time_span &timeout) -> bool
	Join all resources and worker threads.
static auto	queue_user_work_item (const wait_callback &callback) -> void
	Queues a method for execution. The method executes when a thread pool thread becomes available.
static auto	queue_user_work_item (const wait_callback &callback, const xtd::any_object &state) -> void
	Queues a method for execution. The method executes when a thread pool thread becomes available.
static auto	register_wait_for_single_object (wait_handle &wait_object, const wait_or_timer_callback &callback, const xtd::any_object &state, int32 milliseconds_timeout_interval, bool execute_only_once) -> registered_wait_handle
	Registers a delegate to wait for a xtd::threading::wait_handle, specifying a 32-bit signed integer for the time-out in milliseconds.
static auto	register_wait_for_single_object (wait_handle &wait_object, const wait_or_timer_callback &callback, const xtd::any_object &state, int64 milliseconds_timeout_interval, bool execute_only_once) -> registered_wait_handle
	Registers a delegate to wait for a xtd::threading::wait_handle, specifying a 32-bit signed integer for the time-out in milliseconds.
static auto	register_wait_for_single_object (wait_handle &wait_object, const wait_or_timer_callback &callback, const xtd::any_object &state, const time_span &timeout, bool execute_only_once) -> registered_wait_handle
	Registers a delegate to wait for a xtd::threading::wait_handle, specifying a 32-bit signed integer for the time-out in milliseconds.
static auto	register_wait_for_single_object (wait_handle &wait_object, const wait_or_timer_callback &callback, const xtd::any_object &state, uint32 milliseconds_timeout_interval, bool execute_only_once) -> registered_wait_handle
	Registers a delegate to wait for a xtd::threading::wait_handle, specifying a 32-bit signed integer for the time-out in milliseconds.
static auto	set_max_threads (size_t worker_threads, size_t completion_port_threads) -> bool
	Sets the number of requests to the thread pool that can be active concurrently. All requests above that number remain queued until thread pool threads become available.
static auto	set_min_threads (size_t worker_threads, size_t completion_port_threads) -> bool
	Sets the number of idle threads the thread pool maintains in anticipation of new requests.

Member Function Documentation

close()

auto xtd::threading::thread_pool::close ( ) -> void

static

Close all resources and worker threads.

Remarks

The close method waits for the end of running worker threads, but will not wait for unstarted worker threads.

You can use this method to ensure that all pending threads are closed, and that resources are also closed.

#startup_calls xtd::thread_pool::close method.

xtd::threading::thread::join_all, xtd::threading::thread::join_all(int32), xtd::threading::thread::join_all(const xtd::time_span&) methods call xtd::threading::thread_pool::close method too.

get_available_threads()

auto xtd::threading::thread_pool::get_available_threads ( size_t & worker_threads, size_t & completion_port_threads ) -> void

static

Retrieves the difference between the maximum number of thread pool threads returned by the GetMaxThreads method, and the number currently active.

Parameters

worker_threads	The number of available worker threads
completion_port_threads	The number of available asynchronous I/O threads.

Remarks

When xtd::threading::thread_pool::get_available_threads returns, the variable specified by worker_threads contains the number of additional worker threads that can be started, and the variable specified by completion_port_threads contains the number of additional asynchronous I/O threads that can be started.

get_max_threads()

auto xtd::threading::thread_pool::get_max_threads ( size_t & worker_threads, size_t & completion_port_threads ) -> void

static

Retrieves the number of requests to the thread pool that can be active concurrently. All requests above that number remain queued until thread pool threads become available.

Parameters

worker_threads	The maximum number of worker threads in the thread pool.
completion_port_threads	The maximum number of asynchronous I/O threads in the thread pool.

Remarks

When GetMaxThreads returns, the variable specified by worker_threads contains the maximum number of worker threads allowed in the thread pool, and the variable specified by completion_port_threads contains the maximum number of asynchronous I/O threads allowed in the thread pool.

You can use the xtd::threading::thread_pool::get_available_threads method to determine the actual number of threads in the thread pool at any given time.

You can use the xtd::threading::thread_pool::set_max_threads to set the maximum number of worker threads and asynchronous I/O threads in the thread pool.

get_min_threads()

auto xtd::threading::thread_pool::get_min_threads ( size_t & worker_threads, size_t & completion_port_threads ) -> void

static

Retrieves the number of idle threads the thread pool maintains in anticipation of new requests. Always 0 for both.

Parameters

worker_threads	The maximum number of worker threads in the thread pool.
completion_port_threads	The maximum number of asynchronous I/O threads in the thread pool.

join_all() [1/3]

auto xtd::threading::thread_pool::join_all ( ) -> void

static

Join all resources and worker threads.

Remarks

The join_all method waits for the end of running worker threads, but will not wait for unstarted worker threads.

You can use this method to ensure that all pending threads are closed, and that resources are also closed.

#startup_calls xtd::thread_pool::close method.

xtd::threading::thread::join_all, xtd::threading::thread::join_all(int32), xtd::threading::thread::join_all(const xtd::time_span&) methods call xtd::threading::thread_pool::close method too.

join_all() [2/3]

auto xtd::threading::thread_pool::join_all ( int32 milliseconds_timeout ) -> bool

static

Join all resources and worker threads.

Parameters

milliseconds_timeout

The number of milliseconds to wait for all threads to terminate.

Returns

true if all threads have terminated; false if all threads have not terminated after the amount of time specified by the timeout parameter has elapsed.

Remarks

If one or more threads are not joinable, they will be skipped.

You can use this method to ensure that all pending threads are closed, and that resources are also closed.

join_all() [3/3]

auto xtd::threading::thread_pool::join_all ( const time_span & timeout ) -> bool

static

Join all resources and worker threads.

Parameters

timeout

A xtd::time_span set to the amount of time to wait for all threads to terminate.

Returns

true if all threads have terminated; false if all threads have not terminated after the amount of time specified by the timeout parameter has elapsed.

Remarks

If one or more threads are not joinable, they will be skipped.

You can use this method to ensure that all pending threads are closed, and that resources are also closed.

queue_user_work_item() [1/2]

auto xtd::threading::thread_pool::queue_user_work_item ( const wait_callback & callback ) -> void

static

Queues a method for execution. The method executes when a thread pool thread becomes available.

Parameters

callback

A pointer function that represents the method to be executed.

queue_user_work_item() [2/2]

auto xtd::threading::thread_pool::queue_user_work_item ( const wait_callback & callback, const xtd::any_object & state ) -> void

static

Queues a method for execution. The method executes when a thread pool thread becomes available.

Parameters

callback	A pointer function that represents the method to be executed.
state	An object containing data to be used by the method.

register_wait_for_single_object() [1/4]

auto xtd::threading::thread_pool::register_wait_for_single_object ( wait_handle & wait_object, const wait_or_timer_callback & callback, const xtd::any_object & state, int32 milliseconds_timeout_interval, bool execute_only_once ) -> registered_wait_handle

static

Registers a delegate to wait for a xtd::threading::wait_handle, specifying a 32-bit signed integer for the time-out in milliseconds.

Parameters

wait_object	The xtd::threading::wait_handle to register. Use a xtd::threading::wait_handle other than Mutex
callback	A pointer function to call when the wait_object parameter is signaled.
state	The object that is passed to the callback.
milliseconds_timeout_interval	The time-out in milliseconds. If the milliseconds_timeout_interval parameter is 0 (zero), the function tests the object's state and returns immediately. If milliseconds_timeout_interval is -1, the function's time-out interval never elapses.
execute_only_once	true to indicate that the thread will no longer wait on the wait_object parameter after the callback has been called; false to indicate that the timer is reset every time the wait operation completes until the wait is unregistered.

Returns

registered_wait_handle The xtd::threading::registered_wait_handle that encapsulates the native handle.

Exceptions

xtd::argument_out_of_range_exception

The milliseconds_timeout_interval parameter is less than -1.

register_wait_for_single_object() [2/4]

auto xtd::threading::thread_pool::register_wait_for_single_object ( wait_handle & wait_object, const wait_or_timer_callback & callback, const xtd::any_object & state, int64 milliseconds_timeout_interval, bool execute_only_once ) -> registered_wait_handle

static

Registers a delegate to wait for a xtd::threading::wait_handle, specifying a 32-bit signed integer for the time-out in milliseconds.

Parameters

wait_object	The xtd::threading::wait_handle to register. Use a xtd::threading::wait_handle other than Mutex
callback	A pointer function to call when the wait_object parameter is signaled.
state	The object that is passed to the callback.
milliseconds_timeout_interval	The time-out in milliseconds. If the milliseconds_timeout_interval parameter is 0 (zero), the function tests the object's state and returns immediately. If milliseconds_timeout_interval is -1, the function's time-out interval never elapses.
execute_only_once	true to indicate that the thread will no longer wait on the wait_object parameter after the callback has been called; false to indicate that the timer is reset every time the wait operation completes until the wait is unregistered.

Returns

registered_wait_handle The xtd::threading::registered_wait_handle that encapsulates the native handle.

Exceptions

xtd::argument_out_of_range_exception

The milliseconds_timeout_interval parameter is less than -1.

register_wait_for_single_object() [3/4]

auto xtd::threading::thread_pool::register_wait_for_single_object ( wait_handle & wait_object, const wait_or_timer_callback & callback, const xtd::any_object & state, const time_span & timeout, bool execute_only_once ) -> registered_wait_handle

static

Registers a delegate to wait for a xtd::threading::wait_handle, specifying a 32-bit signed integer for the time-out in milliseconds.

Parameters

wait_object	The xtd::threading::wait_handle to register. Use a xtd::threading::wait_handle other than Mutex
callback	A pointer function to call when the wait_object parameter is signaled.
state	The object that is passed to the callback.
timeout	The time-out represented by a time_span.If timeout is 0 (zero), the function tests the object's state and returns immediately.If timeout is -1, the function's time-out interval never elapses.
execute_only_once	true to indicate that the thread will no longer wait on the wait_object parameter after the callback has been called; false to indicate that the timer is reset every time the wait operation completes until the wait is unregistered.

Returns

registered_wait_handle The xtd::threading::registered_wait_handle that encapsulates the native handle.

Exceptions

xtd::argument_out_of_range_exception

The milliseconds_timeout_interval parameter is less than -1.

register_wait_for_single_object() [4/4]

auto xtd::threading::thread_pool::register_wait_for_single_object ( wait_handle & wait_object, const wait_or_timer_callback & callback, const xtd::any_object & state, uint32 milliseconds_timeout_interval, bool execute_only_once ) -> registered_wait_handle

static

Registers a delegate to wait for a xtd::threading::wait_handle, specifying a 32-bit signed integer for the time-out in milliseconds.

Parameters

wait_object	The xtd::threading::wait_handle to register. Use a xtd::threading::wait_handle other than Mutex
callback	A pointer function to call when the wait_object parameter is signaled.
state	The object that is passed to the callback.
milliseconds_timeout_interval	The time-out in milliseconds. If the milliseconds_timeout_interval parameter is 0 (zero), the function tests the object's state and returns immediately. If milliseconds_timeout_interval is -1, the function's time-out interval never elapses.
execute_only_once	true to indicate that the thread will no longer wait on the wait_object parameter after the callback has been called; false to indicate that the timer is reset every time the wait operation completes until the wait is unregistered.

Returns

registered_wait_handle The xtd::threading::registered_wait_handle that encapsulates the native handle.

Exceptions

xtd::argument_out_of_range_exception

The milliseconds_timeout_interval parameter is less than -1.

set_max_threads()

auto xtd::threading::thread_pool::set_max_threads ( size_t worker_threads, size_t completion_port_threads ) -> bool

static

Sets the number of requests to the thread pool that can be active concurrently. All requests above that number remain queued until thread pool threads become available.

Parameters

worker_threads	The maximum number of worker threads in the thread pool.
completion_port_threads	The maximum number of asynchronous I/O threads in the thread pool.

Returns

true if the change is successful; otherwise, false.

set_min_threads()

auto xtd::threading::thread_pool::set_min_threads ( size_t worker_threads, size_t completion_port_threads ) -> bool

static

Sets the number of idle threads the thread pool maintains in anticipation of new requests.

Parameters

worker_threads	The new minimum number of idle worker threads to be maintained by the thread pool.
completion_port_threads	The new minimum number of idle asynchronous I/O threads to be maintained by the thread pool.

Returns

true if the change is successful; otherwise, false.

---

The documentation for this class was generated from the following file:

• xtd.core/include/xtd/threading/thread_pool.hpp