VLink  2.3.0
A high-performance communication middleware
thread_pool.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2026 by Thun Lu. All rights reserved.
3  * Author: Thun Lu <thun.lu@zohomail.cn>
4  * Repo: https://github.com/thun-res/vlink
5  * _ __ __ _ __
6  * | | / / / / (_) ____ / /__
7  * | | / / / / / / / __ \ / //_/
8  * | |/ / / /___ / / / / / / / ,<
9  * |___/ /_____/ /_/ /_/ /_/ /_/|_|
10  *
11  * Licensed under the Apache License, Version 2.0 (the "License");
12  * you may not use this file except in compliance with the License.
13  * You may obtain a copy of the License at
14  *
15  * http://www.apache.org/licenses/LICENSE-2.0
16  *
17  * Unless required by applicable law or agreed to in writing, software
18  * distributed under the License is distributed on an "AS IS" BASIS,
19  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20  * See the License for the specific language governing permissions and
21  * limitations under the License.
22  */
23 
24 /**
25  * @file thread_pool.h
26  * @brief Fixed-size worker pool for parallel task execution.
27  *
28  * @details
29  * @c vlink::ThreadPool launches a configurable number of worker threads at construction
30  * and dispatches submitted tasks to whichever worker is idle. Unlike @c MessageLoop, the
31  * pool has no built-in timer mechanism or loop lifecycle; it is started immediately and
32  * torn down with @c shutdown(). A pool created with zero workers is left in the
33  * shutdown state and rejects every submission.
34  *
35  * Architecture:
36  *
37  * @verbatim
38  * post_task() -----> +---------------------------+
39  * | shared dispatcher queue |
40  * +-----+----------+----------+
41  * | | |
42  * v v v
43  * worker 1 worker 2 ... worker N
44  * | | |
45  * v v v
46  * user task user task user task
47  * @endverbatim
48  *
49  * Queue implementations:
50  *
51  * | Type | Backing queue | Notes |
52  * | ----------------- | ------------------------------------------------ | ------------------------------- |
53  * | @c kNormalType | Mutex-protected @c std::deque (or @c std::pmr) | Default; honours drop policy |
54  * | @c kLockfreeType | @c MpmcQueue (lock-free multi-producer/consumer) | Lower contention overhead |
55  *
56  * Push-side back-pressure strategies are identical to @c MessageLoop::Strategy. They
57  * only affect submission when the queue is full; worker wake-up is always driven by a
58  * condition variable.
59  *
60  * @note
61  * - Tasks may run concurrently; protect shared state externally.
62  * - @c invoke_task() returns a @c std::future; blocking on it from a pool worker can
63  * deadlock if every worker is busy.
64  * - @c is_in_work_thread() can detect re-entrant submissions.
65  *
66  * @par Example
67  * @code
68  * vlink::ThreadPool pool(8);
69  * pool.post_task([] { heavy_work(); });
70  *
71  * auto fut = pool.invoke_task([]() -> int { return compute(); });
72  * int result = fut.get();
73  *
74  * pool.shutdown();
75  * @endcode
76  */
77 
78 #pragma once
79 
80 #include <functional>
81 #include <future>
82 #include <memory>
83 #include <string>
84 #include <tuple>
85 #include <type_traits>
86 #include <utility>
87 #include <vector>
88 
89 #include "./functional.h"
90 #include "./macros.h"
91 #include "./memory_resource.h"
92 #include "./task_handle.h"
93 
94 namespace vlink {
95 
96 /**
97  * @class ThreadPool
98  * @brief Fixed worker pool that consumes a shared task queue.
99  *
100  * @details
101  * Worker threads are created during construction and joined during @c shutdown() or
102  * destruction. A shutdown initiated by a worker detaches that worker instead of
103  * joining itself. The pool object itself is non-copyable.
104  */
106  public:
107  /**
108  * @brief Callback signature used for submitted tasks.
109  *
110  * @details
111  * Move-only (@c MoveFunction<void()>); see @c MessageLoop::Callback for rationale.
112  */
113  using Callback = MoveFunction<void()>;
114 
115  /**
116  * @enum Type
117  * @brief Queue implementation backing the pool.
118  */
119  enum Type : uint8_t {
120  kNormalType = 0, ///< Default mutex-protected FIFO queue.
121  kLockfreeType = 1, ///< Lock-free MPMC queue.
122  };
123 
124  /**
125  * @enum Strategy
126  * @brief Submission-side strategy applied when the bounded queue is full.
127  *
128  * @details
129  * Worker wake-up is independent of this enum. It controls only how @c post_task and
130  * @c invoke_task react when capacity is reached.
131  */
132  enum Strategy : uint8_t {
133  kOptimizationStrategy = 0, ///< Retry up to 10 times with 1 ms sleep; then drop one eligible task and push.
134  kPopStrategy = 1, ///< Immediately drop one eligible task and push the new one.
135  kBlockStrategy = 2, ///< Retry indefinitely with 1 ms sleep until capacity frees up.
136  };
137 
138  /**
139  * @brief Constructs a pool with @p thread_count workers and the default @c kNormalType queue.
140  *
141  * @param thread_count Worker thread count. Default: @c 4. Zero leaves the pool in
142  * the shutdown state.
143  */
144  explicit ThreadPool(size_t thread_count = 4U);
145 
146  /**
147  * @brief Constructs a pool with a custom queue implementation.
148  *
149  * @param thread_count Worker thread count. Zero leaves the pool in the shutdown state.
150  * @param type Queue implementation type.
151  */
152  explicit ThreadPool(size_t thread_count, Type type);
153 
154  /**
155  * @brief Destructor. Calls @c shutdown(); a current worker is detached instead of self-joined.
156  */
157  virtual ~ThreadPool();
158 
159  /**
160  * @brief Assigns a human-readable name to the pool and its workers (used by debuggers).
161  *
162  * @param name Display name.
163  */
164  void set_name(const std::string& name);
165 
166  /**
167  * @brief Returns the display name assigned via @c set_name().
168  *
169  * @return Reference to the stored name string.
170  */
171  [[nodiscard]] const std::string& get_name() const;
172 
173  /**
174  * @brief Returns the queue implementation used by this pool.
175  *
176  * @return Queue type.
177  */
178  [[nodiscard]] Type get_type() const;
179 
180  /**
181  * @brief Returns the current submission-side back-pressure strategy.
182  *
183  * @return Current strategy.
184  */
185  [[nodiscard]] Strategy get_strategy() const;
186 
187  /**
188  * @brief Updates the submission-side back-pressure strategy.
189  *
190  * @param strategy New strategy.
191  */
192  void set_strategy(Strategy strategy);
193 
194  /**
195  * @brief Marks the pool as quitting, drains in-flight tasks, and joins workers.
196  *
197  * @details
198  * After @c shutdown() returns, further submissions are rejected. Workers complete the
199  * task they are currently running plus any already-queued tasks before exiting. When
200  * called from a worker thread the calling worker's handle is detached instead of
201  * joined because a thread cannot join itself; the @c Impl block is kept alive via
202  * @c std::shared_ptr so the detached worker continues to see a valid pool state until
203  * it returns.
204  *
205  * @return @c true on the first successful shutdown; @c false on subsequent calls.
206  */
207  bool shutdown();
208 
209  /**
210  * @brief Submits a task to the queue for execution by a worker thread.
211  *
212  * @details
213  * Thread-safe. Returns @c false when the pool is already shut down or when overflow
214  * handling cannot make room for the new task. Overflow behaviour depends on the
215  * configured @c Strategy:
216  *
217  * - @c kOptimizationStrategy: retry up to 10 times with a 1 ms sleep, then drop one
218  * eligible task and push the new one.
219  * - @c kPopStrategy: drop one eligible task immediately and push the new one.
220  * - @c kBlockStrategy: retry indefinitely with 1 ms sleep until space is available.
221  *
222  * @note Drop-policy semantics:
223  * - @c kNormalType respects @c TaskDropPolicy::kProtected; protected tasks are never
224  * selected as eviction victims, and if every queued task is protected the post
225  * fails and returns @c false.
226  * - @c kLockfreeType does not track per-task drop policy; overflow drop simply removes
227  * one queued task regardless of how it was submitted.
228  *
229  * @param callback Task to execute.
230  * @return @c true when the task was eventually enqueued.
231  */
232  bool post_task(Callback&& callback);
233 
234  /**
235  * @brief Submits a task that produces an observable @c TaskHandle.
236  *
237  * @details
238  * Tracked counterpart of @c post_task(). The returned handle allows callers to wait
239  * for completion, request cooperative cancellation, and observe whether the task was
240  * rejected or dropped before execution.
241  *
242  * @param callback Task to execute.
243  * @param options Optional overflow, drop, and cancellation policy.
244  * @return Handle observing the posted task; the handle remains valid even when the
245  * post is rejected so callers can inspect @c state().
246  */
247  [[nodiscard]] TaskHandle post_task_handle(Callback&& callback, const PostTaskOptions& options = {});
248 
249  /**
250  * @brief Returns the current number of tasks waiting in the queue.
251  *
252  * @return Pending task count.
253  */
254  [[nodiscard]] size_t get_task_count() const;
255 
256  /**
257  * @brief Reports whether the calling thread is one of this pool's workers.
258  *
259  * @return @c true when called from a worker.
260  */
261  [[nodiscard]] bool is_in_work_thread() const;
262 
263  /**
264  * @brief Returns the maximum queue capacity.
265  *
266  * @return Maximum number of tasks that may be queued at the same time.
267  */
268  [[nodiscard]] virtual size_t get_max_task_count() const;
269 
270  /**
271  * @brief Submits a callable to a worker thread and returns a @c std::future for the result.
272  *
273  * @details
274  * Thread-safe. The future is satisfied once the callable returns. When posting fails
275  * the future becomes ready with a @c broken_promise / @c future_error result.
276  *
277  * @warning Do not block on the returned future from a pool worker thread while all
278  * workers are busy; doing so deadlocks the pool.
279  *
280  * @tparam FunctionT Callable type.
281  * @tparam ArgsT Argument types.
282  * @param function Callable to dispatch.
283  * @param args Arguments copied or moved into owned storage and then moved into the call.
284  * Use @c std::ref to borrow an argument explicitly.
285  * @return Future resolved with the callable's result.
286  */
287  template <class FunctionT, class... ArgsT>
288  [[nodiscard]] auto invoke_task(FunctionT&& function, ArgsT&&... args);
289 
290  private:
291  friend class MultiLoop;
292 
293  void init();
294 
295  bool push_task(Callback&& callback, bool droppable,
297  const TaskHandle* submit_handle = nullptr, Callback* dropped_out = nullptr);
298 
299  bool drop_one_normal_task(Callback& dropped);
300 
301  bool drop_one_lockfree_task(Callback& dropped, bool keep_reserved = false);
302 
303  bool reserve_lockfree_task();
304 
305  void release_lockfree_task();
306 
307  bool push_lockfree_task(Callback&& callback);
308 
309  struct Impl;
310  std::shared_ptr<Impl> impl_;
311 
313 };
314 
315 ////////////////////////////////////////////////////////////////
316 /// Details
317 ////////////////////////////////////////////////////////////////
318 
319 template <class FunctionT, class... ArgsT>
320 inline auto ThreadPool::invoke_task(FunctionT&& function, ArgsT&&... args) {
321  auto bound = [function = std::forward<FunctionT>(function),
322  args = std::make_tuple(std::forward<ArgsT>(args)...)]() mutable -> decltype(auto) {
323  return std::apply(
324  [&function](auto&&... unpacked_args) -> decltype(auto) {
325  return std::invoke(function, std::forward<decltype(unpacked_args)>(unpacked_args)...);
326  },
327  std::move(args));
328  };
329 
330  using ResultT = std::invoke_result_t<decltype(bound)&>;
331 
332  if constexpr (kIsSupportMoveFunction) {
333  std::packaged_task<ResultT()> task(std::move(bound));
334  auto res = task.get_future();
335 
336  if VUNLIKELY (!post_task([task = std::move(task)]() mutable { task(); })) {
337  // Destroying the unposted packaged_task makes the returned future ready with broken_promise.
338  }
339 
340  return res;
341  } else {
342  auto task = MemoryResource::make_shared<std::packaged_task<ResultT()>>(std::move(bound));
343  auto res = task->get_future();
344 
345  if VUNLIKELY (!post_task([task]() mutable { (*task)(); })) {
346  task.reset();
347  }
348 
349  return res;
350  }
351 }
352 
353 } // namespace vlink
Pool-backed type-erased callables: copyable vlink::Function and move-only vlink::MoveFunction.
Cross-platform macros for visibility, branch hints, copy prevention, singletons and string helpers.
#define VUNLIKELY(...)
Short alias for VLINK_UNLIKELY.
Definition: macros.h:292
#define VLINK_EXPORT
Definition: macros.h:81
#define VLINK_DISALLOW_COPY_AND_ASSIGN(classname)
Deletes the copy constructor and copy-assignment operator of classname.
Definition: macros.h:174
PMR adapter that lets standard pmr-aware containers allocate through vlink::MemoryPool.
Observable handle returned by tracked task-posting APIs of MessageLoop and ThreadPool.