Botan 3.14.1
Crypto and TLS for C&
Botan::Thread_Pool Class Referencefinal

#include <thread_pool.h>

Public Member Functions

Thread_Pool & operator= (const Thread_Pool &)=delete
Thread_Pool & operator= (Thread_Pool &&)=delete
void queue_thunk (const std::function< void()> &work)
template<class F, class... Args>
auto run (F &&f, Args &&... args) -> Joining_Future< std::invoke_result_t< F, Args... > >
void set_executor (std::shared_ptr< Work_Executor > executor)
void shutdown ()
 Thread_Pool (const Thread_Pool &)=delete
 Thread_Pool (size_t pool_size=0)
 Thread_Pool (std::optional< size_t > pool_size)
 Thread_Pool (Thread_Pool &&)=delete
size_t worker_count () const
 ~Thread_Pool ()

Static Public Member Functions

static Thread_Pool & global_instance ()

Detailed Description

Thread pool for computationally bound tasks

Callers queue fork-join work which is executed in arbitrary order. Do not use this interface for any kind of IO scheduling.

Definition at line 68 of file thread_pool.h.

Constructor & Destructor Documentation

◆ Thread_Pool() [1/4]

Botan::Thread_Pool::Thread_Pool ( std::optional< size_t > pool_size)
explicit

Initialize a thread pool with some number of threads

Parameters
pool_sizenumber of threads in the pool, if 0 then some default value is chosen. If the optional is nullopt then the thread pool is disabled; all work is executed immediately when queued.

The threads are not started until work is first queued.

Definition at line 223 of file thread_pool.cpp.

223 :
224 m_executor(std::make_shared<Internal_Thread_Pool>(opt_pool_size)),
225 m_worker_count(m_executor->max_concurrency()),
226 m_executor_was_set(false) {}

Referenced by global_instance(), operator=(), operator=(), Thread_Pool(), Thread_Pool(), and Thread_Pool().

◆ Thread_Pool() [2/4]

Botan::Thread_Pool::Thread_Pool ( size_t pool_size = 0)
inlineexplicit

Initialize a thread pool with some number of threads

Parameters
pool_sizenumber of threads in the pool, if 0 then some default value is chosen.

Definition at line 91 of file thread_pool.h.

91: Thread_Pool(std::optional<size_t>(pool_size)) {}
Thread_Pool(std::optional< size_t > pool_size)

References Thread_Pool().

◆ ~Thread_Pool()

Botan::Thread_Pool::~Thread_Pool ( )
inline

Definition at line 93 of file thread_pool.h.

93{ shutdown(); }

References shutdown().

◆ Thread_Pool() [3/4]

Botan::Thread_Pool::Thread_Pool ( const Thread_Pool & )
delete

References Thread_Pool().

◆ Thread_Pool() [4/4]

Botan::Thread_Pool::Thread_Pool ( Thread_Pool && )
delete

References Thread_Pool().

Member Function Documentation

◆ global_instance()

Thread_Pool & Botan::Thread_Pool::global_instance ( )
static

Return an instance to a shared thread pool

Definition at line 213 of file thread_pool.cpp.

213 {
214 static Thread_Pool g_thread_pool(global_thread_pool_size());
215 return g_thread_pool;
216}

References Thread_Pool().

Referenced by Botan::Hash_Engine::create_or_null(), and Botan::Work_Executor::set_global().

◆ operator=() [1/2]

Thread_Pool & Botan::Thread_Pool::operator= ( const Thread_Pool & )
delete

References Thread_Pool().

◆ operator=() [2/2]

Thread_Pool & Botan::Thread_Pool::operator= ( Thread_Pool && )
delete

References queue_thunk(), and Thread_Pool().

◆ queue_thunk()

void Botan::Thread_Pool::queue_thunk ( const std::function< void()> & work)

Definition at line 273 of file thread_pool.cpp.

273 {
274 /*
275 * Immediately execute tasks which are queued from within work this pool is
276 * already running. Otherwise there is risk of deadlock.
277 *
278 * This holds even during shutdown: the nested task is part of work that is
279 * already running, and rejecting it would only cause that work to fail.
280 *
281 * This could be improved, with a bit more complexity, by a "helping join";
282 * instead of just blocking, the thread runs any queued tasks until the one it
283 * is waiting on has completed.
284 */
285 if(Running_Pool_Work::active_for(this)) {
286 return work();
287 }
288
289 // The copy keeps the executor alive until the work has been handed over
290 const auto executor = [this]() {
291 const std::scoped_lock lock(m_mutex);
292
293 if(!m_executor) {
294 throw Invalid_State("Cannot add work after thread pool has shut down");
295 }
296
297 return m_executor;
298 }();
299
300 // Only the pointer value is used, as the marker; in-flight work never
301 // touches the pool itself, so an executor may finish it after shutdown
302 const auto wrapped = [this, work]() {
303 const Running_Pool_Work scope(this);
304 work();
305 };
306
307 try {
308 executor->queue_work(wrapped);
309 } catch(...) {
310 // The executor refused the work, so run it here instead
311 wrapped();
312 }
313}
secure_vector< T > lock(const std::vector< T > &in)
Definition secmem.h:145

References Botan::lock().

Referenced by operator=(), and run().

◆ run()

template<class F, class... Args>
auto Botan::Thread_Pool::run ( F && f,
Args &&... args ) -> Joining_Future< std::invoke_result_t< F, Args... > >
inline

Queue fork-join work which will be executed in arbitrary order

Definition at line 137 of file thread_pool.h.

137 {
138 using return_type = std::invoke_result_t<F, Args...>;
139
140 const auto future_work = std::bind(std::forward<F>(f), std::forward<Args>(args)...); // NOLINT(*-avoid-bind)
141 const auto task = std::make_shared<std::packaged_task<return_type()>>(future_work);
142 auto future_result = task->get_future();
143 queue_thunk([task]() { (*task)(); });
144 // Wrapped only once queued; otherwise unwinding would wait on a task
145 // still owned by this frame
146 return Joining_Future<return_type>(std::move(future_result));
147 }
void queue_thunk(const std::function< void()> &work)

References queue_thunk().

◆ set_executor()

void Botan::Thread_Pool::set_executor ( std::shared_ptr< Work_Executor > executor)

Install an executor which runs queued work in place of the pool's threads

May be called at most once; the executor then remains in use for the lifetime of the pool. Any threads already started finish their queued work and exit.

Throws Invalid_State if an executor is already set, or if called from within work run by this pool.

Definition at line 233 of file thread_pool.cpp.

233 {
234 BOTAN_ARG_CHECK(executor != nullptr, "Thread_Pool::set_executor executor must not be null");
235
236 // Would join the thread this is running on
237 if(Running_Pool_Work::active_for(this)) {
238 throw Invalid_State("Cannot set the executor from within work run by the thread pool");
239 }
240
241 // Queried outside the lock, since the executor may itself use the library
242 const size_t concurrency = executor->max_concurrency();
243
244 // Releasing the internal pool drains its queue and joins its threads, so
245 // it is held until after the lock is dropped
246 const auto internal_pool = [&]() {
247 const std::scoped_lock lock(m_mutex);
248
249 if(m_executor_was_set) {
250 throw Invalid_State("Thread pool executor has already been set");
251 }
252
253 if(!m_executor) {
254 throw Invalid_State("Cannot set the executor after the thread pool has shut down");
255 }
256
257 m_executor_was_set = true;
258 m_worker_count = concurrency;
259 return std::exchange(m_executor, std::move(executor));
260 }();
261}
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33

References BOTAN_ARG_CHECK, and Botan::lock().

Referenced by Botan::Work_Executor::set_global().

◆ shutdown()

void Botan::Thread_Pool::shutdown ( )

Definition at line 263 of file thread_pool.cpp.

263 {
264 // Releasing the internal pool drains its queue and joins its threads, so
265 // it is held until after the lock is dropped
266 const auto executor = [this]() {
267 const std::scoped_lock lock(m_mutex);
268 m_worker_count = 0;
269 return std::exchange(m_executor, nullptr);
270 }();
271}

References Botan::lock().

Referenced by ~Thread_Pool().

◆ worker_count()

size_t Botan::Thread_Pool::worker_count ( ) const

Return the number of threads available to run queued work

With an executor installed this is the max_concurrency it reported when it was installed. Otherwise it is the number of threads in the pool, where zero means the pool is disabled and all work runs in the calling thread. Returns zero once the pool has shut down.

Definition at line 228 of file thread_pool.cpp.

228 {
229 const std::scoped_lock lock(m_mutex);
230 return m_worker_count;
231}

References Botan::lock().


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