Botan 3.14.1
Crypto and TLS for C&
work_executor.h
Go to the documentation of this file.
1/*
2* (C) 2026 Jack Lloyd
3*
4* Botan is released under the Simplified BSD License (see license.txt)
5*/
6
7#ifndef BOTAN_WORK_EXECUTOR_H_
8#define BOTAN_WORK_EXECUTOR_H_
9
10#include <botan/types.h>
11#include <functional>
12#include <memory>
13
14namespace Botan {
15
16/**
17* An application provided replacement for the library's thread pool
18*
19* Some operations split their work across threads. By default this uses a
20* thread pool internal to the library. An application can instead route that
21* work to threads of its own choosing by installing an implementation of this
22* interface with set_global.
23*
24* All such work is fork-join: the thread which queued the work blocks until it
25* has completed. The executor must therefore guarantee forward progress; each
26* piece of work must either run on a thread which is not itself blocked waiting
27* for it, or be run directly within queue_work. In particular, an executor
28* backed by a fixed set of threads should run work directly when queue_work is
29* called from one of those threads, since otherwise all of them may end up
30* blocked waiting on each other.
31*
32* The library may call queue_work and max_concurrency from any number of
33* threads at once, so both must be thread safe.
34*/
36 public:
37 Work_Executor() = default;
38 virtual ~Work_Executor() = default;
39
40 Work_Executor(const Work_Executor&) = delete;
44
45 /**
46 * Queue a piece of work
47 *
48 * The work must run exactly once, on any thread. Running it directly
49 * within this call is permitted. If this call throws, the work is taken
50 * to not have been accepted, and is run in the calling thread instead.
51 * The work never throws.
52 */
53 virtual void queue_work(std::function<void()> work) = 0;
54
55 /**
56 * Return the number of threads available to run queued work
57 *
58 * This is a hint used to decide how finely to split divisible work.
59 * Returning 1 (or 0) means such work is not split at all, though the
60 * executor may still be asked to run work which is parallel by nature.
61 * It is queried when the executor is installed.
62 */
63 virtual size_t max_concurrency() const = 0;
64
65 /**
66 * Install an executor which replaces the library's internal thread pool
67 *
68 * This may be called at most once. The executor then remains in use, and
69 * is referenced by the library, for the remainder of the process. That
70 * reference is released during static destruction at process exit, so
71 * keep a reference of your own to control when the executor is destroyed.
72 *
73 * Any threads the internal pool has already started finish their queued
74 * work and exit. Ideally this is called before any other use of the
75 * library, so that those threads are never started at all.
76 *
77 * Throws Invalid_State if an executor is already installed, or if called
78 * from within work queued by the library.
79 */
80 static void set_global(std::shared_ptr<Work_Executor> executor);
81};
82
83} // namespace Botan
84
85#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
Work_Executor & operator=(Work_Executor &&)=delete
Work_Executor(Work_Executor &&)=delete
virtual size_t max_concurrency() const =0
static void set_global(std::shared_ptr< Work_Executor > executor)
virtual ~Work_Executor()=default
virtual void queue_work(std::function< void()> work)=0
Work_Executor & operator=(const Work_Executor &)=delete
Work_Executor(const Work_Executor &)=delete