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/threading/auto_reset_event>
#include <xtd/threading/thread_pool>
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/random>
#include <xtd/startup>
 
using namespace xtd;
using namespace xtd::threading;
 
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(std::any 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<std::any> 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, std::any) 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 void	close ()
	Close all resources and worker threads.
static void	get_available_threads (size_t &worker_threads, size_t &completion_port_threads)
	Retrieves the difference between the maximum number of thread pool threads returned by the GetMaxThreads method, and the number currently active.
static void	get_max_threads (size_t &worker_threads, size_t &completion_port_threads)
	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 void	get_min_threads (size_t &worker_threads, size_t &completion_port_threads)
	Retrieves the number of idle threads the thread pool maintains in anticipation of new requests. Always 0 for both.
static void	join_all ()
	Join all resources and worker threads.
static bool	join_all (int32 milliseconds_timeout)
	Join all resources and worker threads.
static bool	join_all (const time_span &timeout)
	Join all resources and worker threads.
static bool	queue_user_work_item (const wait_callback &callback)
	Queues a method for execution. The method executes when a thread pool thread becomes available.
static bool	queue_user_work_item (const wait_callback &callback, std::any state)
	Queues a method for execution. The method executes when a thread pool thread becomes available.
static registered_wait_handle	register_wait_for_single_object (wait_handle &wait_object, const wait_or_timer_callback &callback, std::any state, int32 milliseconds_timeout_interval, bool execute_only_once)
	Registers a delegate to wait for a xtd::threading::wait_handle, specifying a 32-bit signed integer for the time-out in milliseconds.
static registered_wait_handle	register_wait_for_single_object (wait_handle &wait_object, const wait_or_timer_callback &callback, std::any state, int64 milliseconds_timeout_interval, bool execute_only_once)
	Registers a delegate to wait for a xtd::threading::wait_handle, specifying a 32-bit signed integer for the time-out in milliseconds.
static registered_wait_handle	register_wait_for_single_object (wait_handle &wait_object, const wait_or_timer_callback &callback, std::any state, const time_span &timeout, bool execute_only_once)
	Registers a delegate to wait for a xtd::threading::wait_handle, specifying a 32-bit signed integer for the time-out in milliseconds.
static registered_wait_handle	register_wait_for_single_object (wait_handle &wait_object, const wait_or_timer_callback &callback, std::any state, uint32 milliseconds_timeout_interval, bool execute_only_once)
	Registers a delegate to wait for a xtd::threading::wait_handle, specifying a 32-bit signed integer for the time-out in milliseconds.
static bool	set_max_threads (size_t worker_threads, size_t completion_port_threads)
	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 bool	set_min_threads (size_t worker_threads, size_t completion_port_threads)
	Sets the number of idle threads the thread pool maintains in anticipation of new requests.

Member Function Documentation

close()

static void xtd::threading::thread_pool::close ( )

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()

static void xtd::threading::thread_pool::get_available_threads ( size_t &  worker_threads, size_t &  completion_port_threads  )

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()

static void xtd::threading::thread_pool::get_max_threads ( size_t &  worker_threads, size_t &  completion_port_threads  )

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()

static void xtd::threading::thread_pool::get_min_threads ( size_t &  worker_threads, size_t &  completion_port_threads  )

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]

static void xtd::threading::thread_pool::join_all ( )

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]

static bool xtd::threading::thread_pool::join_all ( int32  milliseconds_timeout )

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]

static bool xtd::threading::thread_pool::join_all ( const time_span &  timeout )

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]

static bool xtd::threading::thread_pool::queue_user_work_item ( const wait_callback &  callback )

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.

Returns

true if the method is successfully queued; NotSupportException is thrown if the work item could not be queued

queue_user_work_item() [2/2]

static bool xtd::threading::thread_pool::queue_user_work_item ( const wait_callback &  callback, std::any  state  )

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.

Returns

true if the method is successfully queued; NotSupportedException is thrown if the work item could not be queued

register_wait_for_single_object() [1/4]

static registered_wait_handle xtd::threading::thread_pool::register_wait_for_single_object ( wait_handle &  wait_object, const wait_or_timer_callback &  callback, std::any  state, int32  milliseconds_timeout_interval, bool  execute_only_once  )

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]

static registered_wait_handle xtd::threading::thread_pool::register_wait_for_single_object ( wait_handle &  wait_object, const wait_or_timer_callback &  callback, std::any  state, int64  milliseconds_timeout_interval, bool  execute_only_once  )

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]

static registered_wait_handle xtd::threading::thread_pool::register_wait_for_single_object ( wait_handle &  wait_object, const wait_or_timer_callback &  callback, std::any  state, const time_span &  timeout, bool  execute_only_once  )

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]

static registered_wait_handle xtd::threading::thread_pool::register_wait_for_single_object ( wait_handle &  wait_object, const wait_or_timer_callback &  callback, std::any  state, uint32  milliseconds_timeout_interval, bool  execute_only_once  )

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()

static bool xtd::threading::thread_pool::set_max_threads ( size_t  worker_threads, size_t  completion_port_threads  )

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()

static bool xtd::threading::thread_pool::set_min_threads ( size_t  worker_threads, size_t  completion_port_threads  )

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.h