Detailed Description

ThreadPool starts a fixed number p of std::threads which process Jobs that are enqueued into a concurrent job queue.

The jobs themselves can enqueue more jobs that will be processed when a thread is ready.

The ThreadPool can either run until

all jobs are done AND all threads are idle, when called with loop_until_empty(), or
until Terminate() is called when run with loop_until_terminate().

Jobs are plain tlx::Delegate<void()> objects, hence the pool user must pass in ALL CONTEXT himself. The best method to pass parameters to Jobs is to use lambda captures. Alternatively, old-school objects implementing operator(), or std::binds can be used.

The ThreadPool uses a condition variable to wait for new jobs and does not remain busy waiting.

Note that the threads in the pool start before the two loop functions are called. In case of loop_until_empty() the threads continue to be idle afterwards, and can be reused, until the ThreadPool is destroyed.

ThreadPool pool(4); // pool with 4 threads
int value = 0;
pool.enqueue([&value]() {
  // increment value in another thread.
  ++value;
});
pool.loop_until_empty();

Definition at line 64 of file thread_pool.hpp.

Collaboration diagram for ThreadPool:

#include <thread_pool.hpp>

Public Types
using	InitThread = Delegate< void(size_t)>

using	Job = Delegate< void()>

Public Member Functions
	ThreadPool (size_t num_threads=std::thread::hardware_concurrency(), InitThread &&init_thread=InitThread())
	Construct running thread pool of num_threads. More...

	ThreadPool (const ThreadPool &)=delete
	non-copyable: delete copy-constructor More...

	~ThreadPool ()
	Stop processing jobs, terminate threads. More...

size_t	done () const
	Return number of jobs currently completed. More...

void	enqueue (Job &&job)
	enqueue a Job, the caller must pass in all context using captures. More...

bool	has_idle () const
	true if any thread is idle (= waiting for jobs) More...

size_t	idle () const
	return number of idle threads in pool More...

void	loop_until_empty ()

void	loop_until_terminate ()
	Loop until terminate flag was set. More...

ThreadPool &	operator= (const ThreadPool &)=delete
	non-copyable: delete assignment operator More...

size_t	size () const
	Return number of threads in pool. More...

void	terminate ()

std::thread &	thread (size_t i)
	Return thread handle to thread i. More...

Private Member Functions
void	worker (size_t p)
	Worker function, one per thread is started. More...

Private Attributes
std::atomic< size_t >	busy_ = { 0 }
	Counter for number of threads busy. More...

std::condition_variable	cv_finished_
	Condition variable to signal when a jobs finishes. More...

std::condition_variable	cv_jobs_

std::atomic< size_t >	done_ = { 0 }
	Counter for total number of jobs executed. More...

std::atomic< size_t >	idle_ = { 0 }
	Counter for number of idle threads waiting for a job. More...

InitThread	init_thread_
	Run once per worker thread. More...

std::deque< Job >	jobs_
	Deque of scheduled jobs. More...

std::mutex	mutex_
	Mutex used to access the queue of scheduled jobs. More...

std::atomic< bool >	terminate_ = { false }
	Flag whether to terminate. More...

simple_vector< std::thread >	threads_
	threads in pool More...

Member Typedef Documentation

◆ InitThread

using InitThread = Delegate<void (size_t)>

Definition at line 68 of file thread_pool.hpp.

◆ Job

using Job = Delegate<void ()>

Definition at line 67 of file thread_pool.hpp.

Constructor & Destructor Documentation

◆ ThreadPool() [1/2]

ThreadPool	(	size_t	num_threads = `std::thread::hardware_concurrency()`,
		InitThread &&	init_thread = `InitThread()`
	)

Construct running thread pool of num_threads.

Definition at line 17 of file thread_pool.cpp.

References ThreadPool::threads_, and ThreadPool::worker().

◆ ThreadPool() [2/2]

ThreadPool ( const ThreadPool & )

delete

non-copyable: delete copy-constructor

◆ ~ThreadPool()

~ThreadPool ( )

Stop processing jobs, terminate threads.

Definition at line 25 of file thread_pool.cpp.

References ThreadPool::cv_jobs_, tlx::join(), ThreadPool::mutex_, ThreadPool::terminate_, and ThreadPool::threads_.

Member Function Documentation

◆ done()

size_t done ( ) const

Return number of jobs currently completed.

Definition at line 65 of file thread_pool.cpp.

References ThreadPool::done_.

◆ enqueue()

void enqueue ( Job && job )

enqueue a Job, the caller must pass in all context using captures.

Definition at line 37 of file thread_pool.cpp.

References ThreadPool::cv_jobs_, ThreadPool::jobs_, and ThreadPool::mutex_.

◆ has_idle()

bool has_idle ( ) const

true if any thread is idle (= waiting for jobs)

Definition at line 77 of file thread_pool.cpp.

References ThreadPool::idle_.

◆ idle()

size_t idle ( ) const

return number of idle threads in pool

Definition at line 73 of file thread_pool.cpp.

References ThreadPool::idle_.

◆ loop_until_empty()

void loop_until_empty ( )

Loop until no more jobs are in the queue AND all threads are idle. When this occurs, this method exits, however, the threads remain active.

Definition at line 43 of file thread_pool.cpp.

References ThreadPool::busy_, ThreadPool::cv_finished_, ThreadPool::jobs_, and ThreadPool::mutex_.

◆ loop_until_terminate()

void loop_until_terminate ( )

Loop until terminate flag was set.

Definition at line 49 of file thread_pool.cpp.

References ThreadPool::busy_, ThreadPool::cv_finished_, ThreadPool::mutex_, and ThreadPool::terminate_.

◆ operator=()

ThreadPool& operator= ( const ThreadPool & )

delete

non-copyable: delete assignment operator

◆ size()

size_t size ( ) const

Return number of threads in pool.

Definition at line 69 of file thread_pool.cpp.

References ThreadPool::threads_.

◆ terminate()

void terminate ( )

Terminate thread pool gracefully, wait until currently running jobs finish and then exit. This should be called from within one of the enqueue jobs or from an outside thread.

Definition at line 55 of file thread_pool.cpp.

References ThreadPool::cv_finished_, ThreadPool::cv_jobs_, ThreadPool::mutex_, and ThreadPool::terminate_.

◆ thread()

std::thread & thread ( size_t i )

Return thread handle to thread i.

Definition at line 81 of file thread_pool.cpp.

References ThreadPool::threads_.

◆ worker()

void worker ( size_t p )

private

Worker function, one per thread is started.

Definition at line 86 of file thread_pool.cpp.

References ThreadPool::busy_, ThreadPool::cv_finished_, ThreadPool::cv_jobs_, ThreadPool::done_, ThreadPool::idle_, ThreadPool::init_thread_, ThreadPool::jobs_, ThreadPool::mutex_, and ThreadPool::terminate_.

Referenced by ThreadPool::ThreadPool().

Member Data Documentation

◆ busy_

std::atomic<size_t> busy_ = { 0 }

private

Counter for number of threads busy.

Definition at line 87 of file thread_pool.hpp.

Referenced by ThreadPool::loop_until_empty(), ThreadPool::loop_until_terminate(), and ThreadPool::worker().

◆ cv_finished_

std::condition_variable cv_finished_

private

Condition variable to signal when a jobs finishes.

Definition at line 84 of file thread_pool.hpp.

Referenced by ThreadPool::loop_until_empty(), ThreadPool::loop_until_terminate(), ThreadPool::terminate(), and ThreadPool::worker().

◆ cv_jobs_

std::condition_variable cv_jobs_

private

Condition variable used to notify that a new job has been inserted in the queue.

Definition at line 82 of file thread_pool.hpp.

Referenced by ThreadPool::enqueue(), ThreadPool::terminate(), ThreadPool::worker(), and ThreadPool::~ThreadPool().

◆ done_

std::atomic<size_t> done_ = { 0 }

private

Counter for total number of jobs executed.

Definition at line 91 of file thread_pool.hpp.

Referenced by ThreadPool::done(), and ThreadPool::worker().

◆ idle_

std::atomic<size_t> idle_ = { 0 }

private

Counter for number of idle threads waiting for a job.

Definition at line 89 of file thread_pool.hpp.

Referenced by ThreadPool::has_idle(), ThreadPool::idle(), and ThreadPool::worker().

◆ init_thread_

InitThread init_thread_

private

Run once per worker thread.

Definition at line 97 of file thread_pool.hpp.

Referenced by ThreadPool::worker().

◆ jobs_

std::deque<Job> jobs_

private

Deque of scheduled jobs.

Definition at line 72 of file thread_pool.hpp.

Referenced by ThreadPool::enqueue(), ThreadPool::loop_until_empty(), and ThreadPool::worker().

◆ mutex_

std::mutex mutex_

private

Mutex used to access the queue of scheduled jobs.

Definition at line 75 of file thread_pool.hpp.

Referenced by ThreadPool::enqueue(), ThreadPool::loop_until_empty(), ThreadPool::loop_until_terminate(), ThreadPool::terminate(), ThreadPool::worker(), and ThreadPool::~ThreadPool().

◆ terminate_

std::atomic<bool> terminate_ = { false }

private

Flag whether to terminate.

Definition at line 94 of file thread_pool.hpp.

Referenced by ThreadPool::loop_until_terminate(), ThreadPool::terminate(), ThreadPool::worker(), and ThreadPool::~ThreadPool().

◆ threads_

simple_vector<std::thread> threads_

private

threads in pool

Definition at line 78 of file thread_pool.hpp.

Referenced by ThreadPool::size(), ThreadPool::thread(), ThreadPool::ThreadPool(), and ThreadPool::~ThreadPool().

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

extlib/tlx/tlx/thread_pool.hpp
extlib/tlx/tlx/thread_pool.cpp

Detailed Description

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Member Typedef Documentation

◆ InitThread

◆ Job

Constructor & Destructor Documentation

◆ ThreadPool() [1/2]

◆ ThreadPool() [2/2]

◆ ~ThreadPool()

Member Function Documentation

◆ done()

◆ enqueue()

◆ has_idle()

◆ idle()

◆ loop_until_empty()

◆ loop_until_terminate()

◆ operator=()

◆ size()

◆ terminate()

◆ thread()

◆ worker()

Member Data Documentation

◆ busy_

◆ cv_finished_

◆ cv_jobs_

◆ done_

◆ idle_

◆ init_thread_

◆ jobs_

◆ mutex_

◆ terminate_

◆ threads_