Updated to v3.5.0

.clang-format

@@ -0,0 +1,190 @@
+---
+Language: Cpp
+AccessModifierOffset: -4
+AlignAfterOpenBracket: Align
+AlignArrayOfStructures: None
+AlignConsecutiveMacros: None
+AlignConsecutiveAssignments: None
+AlignConsecutiveBitFields: None
+AlignConsecutiveDeclarations: None
+AlignEscapedNewlines: Right
+AlignOperands: Align
+AlignTrailingComments: true
+AllowAllArgumentsOnNextLine: true
+AllowAllParametersOfDeclarationOnNextLine: true
+AllowShortEnumsOnASingleLine: true
+AllowShortBlocksOnASingleLine: Never
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: Empty
+AllowShortLambdasOnASingleLine: All
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakAfterDefinitionReturnType: None
+AlwaysBreakAfterReturnType: None
+AlwaysBreakBeforeMultilineStrings: false
+AlwaysBreakTemplateDeclarations: Yes
+AttributeMacros:
+    - __capability
+BinPackArguments: true
+BinPackParameters: true
+BraceWrapping:
+    AfterCaseLabel: false
+    AfterClass: false
+    AfterControlStatement: Never
+    AfterEnum: false
+    AfterFunction: false
+    AfterNamespace: false
+    AfterObjCDeclaration: false
+    AfterStruct: false
+    AfterUnion: false
+    AfterExternBlock: false
+    BeforeCatch: false
+    BeforeElse: false
+    BeforeLambdaBody: false
+    BeforeWhile: false
+    IndentBraces: false
+    SplitEmptyFunction: true
+    SplitEmptyRecord: true
+    SplitEmptyNamespace: true
+BreakBeforeBinaryOperators: None
+BreakBeforeConceptDeclarations: true
+BreakBeforeBraces: Allman
+BreakBeforeInheritanceComma: false
+BreakInheritanceList: BeforeColon
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializersBeforeComma: false
+BreakConstructorInitializers: BeforeColon
+BreakAfterJavaFieldAnnotations: false
+BreakStringLiterals: true
+ColumnLimit: 10000
+CommentPragmas: "^ IWYU pragma:"
+QualifierAlignment: Leave
+CompactNamespaces: false
+ConstructorInitializerIndentWidth: 4
+ContinuationIndentWidth: 4
+Cpp11BracedListStyle: true
+DeriveLineEnding: true
+DerivePointerAlignment: false
+DisableFormat: false
+EmptyLineAfterAccessModifier: Never
+EmptyLineBeforeAccessModifier: LogicalBlock
+ExperimentalAutoDetectBinPacking: false
+PackConstructorInitializers: BinPack
+BasedOnStyle: ""
+ConstructorInitializerAllOnOneLineOrOnePerLine: false
+AllowAllConstructorInitializersOnNextLine: true
+FixNamespaceComments: true
+ForEachMacros:
+    - foreach
+    - Q_FOREACH
+    - BOOST_FOREACH
+IfMacros:
+    - KJ_IF_MAYBE
+IncludeBlocks: Preserve
+IncludeCategories:
+    - Regex: '^"(llvm|llvm-c|clang|clang-c)/'
+      Priority: 2
+      SortPriority: 0
+      CaseSensitive: false
+    - Regex: '^(<|"(gtest|gmock|isl|json)/)'
+      Priority: 3
+      SortPriority: 0
+      CaseSensitive: false
+    - Regex: ".*"
+      Priority: 1
+      SortPriority: 0
+      CaseSensitive: false
+IncludeIsMainRegex: "(Test)?$"
+IncludeIsMainSourceRegex: ""
+IndentAccessModifiers: false
+IndentCaseLabels: false
+IndentCaseBlocks: false
+IndentGotoLabels: true
+IndentPPDirectives: None
+IndentExternBlock: AfterExternBlock
+IndentRequires: false
+IndentWidth: 4
+IndentWrappedFunctionNames: false
+InsertTrailingCommas: None
+JavaScriptQuotes: Leave
+JavaScriptWrapImports: true
+KeepEmptyLinesAtTheStartOfBlocks: true
+LambdaBodyIndentation: Signature
+MacroBlockBegin: ""
+MacroBlockEnd: ""
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: None
+ObjCBinPackProtocolList: Auto
+ObjCBlockIndentWidth: 4
+ObjCBreakBeforeNestedBlockParam: true
+ObjCSpaceAfterProperty: false
+ObjCSpaceBeforeProtocolList: true
+PenaltyBreakAssignment: 2
+PenaltyBreakBeforeFirstCallParameter: 19
+PenaltyBreakComment: 300
+PenaltyBreakFirstLessLess: 120
+PenaltyBreakOpenParenthesis: 0
+PenaltyBreakString: 1000
+PenaltyBreakTemplateDeclaration: 10
+PenaltyExcessCharacter: 1000000
+PenaltyReturnTypeOnItsOwnLine: 60
+PenaltyIndentedWhitespace: 0
+PointerAlignment: Left
+PPIndentWidth: -1
+ReferenceAlignment: Pointer
+ReflowComments: true
+RemoveBracesLLVM: false
+SeparateDefinitionBlocks: Leave
+ShortNamespaceLines: 1
+SortIncludes: CaseSensitive
+SortJavaStaticImport: Before
+SortUsingDeclarations: true
+SpaceAfterCStyleCast: false
+SpaceAfterLogicalNot: false
+SpaceAfterTemplateKeyword: true
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeCaseColon: false
+SpaceBeforeCpp11BracedList: true
+SpaceBeforeCtorInitializerColon: true
+SpaceBeforeInheritanceColon: true
+SpaceBeforeParens: ControlStatements
+SpaceBeforeParensOptions:
+    AfterControlStatements: true
+    AfterForeachMacros: true
+    AfterFunctionDefinitionName: false
+    AfterFunctionDeclarationName: false
+    AfterIfMacros: true
+    AfterOverloadedOperator: false
+    BeforeNonEmptyParentheses: false
+SpaceAroundPointerQualifiers: Default
+SpaceBeforeRangeBasedForLoopColon: true
+SpaceInEmptyBlock: false
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 1
+SpacesInAngles: Never
+SpacesInConditionalStatement: false
+SpacesInContainerLiterals: true
+SpacesInCStyleCastParentheses: false
+SpacesInLineCommentPrefix:
+    Minimum: 1
+    Maximum: -1
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+SpaceBeforeSquareBrackets: false
+BitFieldColonSpacing: Both
+Standard: Latest
+StatementAttributeLikeMacros:
+    - Q_EMIT
+StatementMacros:
+    - Q_UNUSED
+    - QT_REQUIRE_VERSION
+TabWidth: 4
+UseCRLF: false
+UseTab: Never
+WhitespaceSensitiveMacros:
+    - STRINGIZE
+    - PP_STRINGIZE
+    - BOOST_PP_STRINGIZE
+    - NS_SWIFT_NAME
+    - CF_SWIFT_NAME
+---

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,37 @@
+---
+name: Bug report
+about: Found a bug? Report it here.
+title: "[BUG]"
+labels: bug
+assignees: bshoshany
+
+---
+
+**Describe the bug**
+
+A clear and concise description of what the bug is.
+
+**Minimal working example**
+
+A short but complete program that can be compiled to reproduce the error. Paste the program between the two code fences. If it's too long or requires multiple files, attach the file(s) instead.
+
+```cpp
+```
+
+**Behavior**
+
+What behavior did you expect to get? What actually happened? If the code failed to compile, please include the full output of the compiler.
+
+**System information**
+
+* CPU model, architecture, # of cores and threads:
+* Operating system:
+* Name and version of C++ compiler:
+* Full command used for compiling, including all compiler flags:
+* Thread pool library version:
+
+(Please note that only the latest version of the thread pool library is supported.)
+
+**Additional information**
+
+Include any additional information here.

.github/ISSUE_TEMPLATE/failed-tests.md

@@ -0,0 +1,26 @@
+---
+name: Failed tests
+about: The provided automated tests failed on your system? Report it here.
+title: "[TEST]"
+labels: bug
+assignees: bshoshany
+
+---
+
+**System information**
+
+* CPU model, architecture, # of cores and threads:
+* Operating system:
+* Name and version of C++ compiler:
+* Full command used for compiling, including all compiler flags:
+* Thread pool library version:
+
+(Please note that only the latest version of the thread pool library is supported.)
+
+**Log file**
+
+Please attach the log file generated by the automated test program to this issue.
+
+**Additional information**
+
+Include any additional information here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Want a new feature? Suggest it here.
+title: "[REQ]"
+labels: enhancement
+assignees: bshoshany
+
+---
+
+**Describe the new feature**
+
+A clear and concise description of the feature you want.
+
+**Code example**
+
+An example of code that utilizes the suggested feature. Paste or write it between the two code fences.
+
+```cpp
+```
+
+**Additional information**
+
+Include any additional information here.

.github/pull_request_template.md

@@ -0,0 +1,26 @@
+**Pull request policy (please read)**
+
+> Contributions are always welcome. However, I release my projects in cumulative updates after editing and testing them locally on my system, so my policy is not to accept any pull requests. If you open a pull request, and I decide to incorporate your suggestion into the project, I will first modify your code to comply with the project's coding conventions (formatting, syntax, naming, comments, programming practices, etc.), and perform some tests to ensure that the change doesn't break anything. I will then merge it into the next release of the project, possibly together with some other changes. The new release will also include a note in `CHANGELOG.md` with a link to your pull request, and modifications to the documentation in `README.md` as needed.
+
+**Describe the changes**
+
+What does your pull request fix or add to the library?
+
+**Style**
+
+Have you formatted your code using the `.clang-format` file attached to this project?
+
+**Testing**
+
+Have you tested the new code using the provided automated test program `BS_thread_pool_test.cpp` (preferably with the provided multi-compiler test script `BS_thread_pool_test.ps1`) and/or performed any other tests to ensure that the new code works correctly?
+
+If so, please provide information about the test system(s):
+
+* CPU model, architecture, # of cores and threads:
+* Operating system:
+* Name and version of C++ compiler:
+* Full command used for compiling, including all compiler flags:
+
+**Additional information**
+
+Include any additional information here.

.gitignore

@@ -0,0 +1 @@
+build

CHANGELOG.md

@@ -0,0 +1,262 @@
+# `BS::thread_pool`: a fast, lightweight, and easy-to-use C++17 thread pool library
+
+By Barak Shoshany\
+Email: <baraksh@gmail.com>\
+Website: <https://baraksh.com/>\
+GitHub: <https://github.com/bshoshany>
+
+* [Version history](#version-history)
+    * [v3.5.0 (2023-05-25)](#v350-2023-05-25)
+    * [v3.4.0 (2023-05-12)](#v340-2023-05-12)
+    * [v3.3.0 (2022-08-03)](#v330-2022-08-03)
+    * [v3.2.0 (2022-07-28)](#v320-2022-07-28)
+    * [v3.1.0 (2022-07-13)](#v310-2022-07-13)
+    * [v3.0.0 (2022-05-30)](#v300-2022-05-30)
+    * [v2.0.0 (2021-08-14)](#v200-2021-08-14)
+    * [v1.9 (2021-07-29)](#v19-2021-07-29)
+    * [v1.8 (2021-07-28)](#v18-2021-07-28)
+    * [v1.7 (2021-06-02)](#v17-2021-06-02)
+    * [v1.6 (2021-05-26)](#v16-2021-05-26)
+    * [v1.5 (2021-05-07)](#v15-2021-05-07)
+    * [v1.4 (2021-05-05)](#v14-2021-05-05)
+    * [v1.3 (2021-05-03)](#v13-2021-05-03)
+    * [v1.2 (2021-04-29)](#v12-2021-04-29)
+    * [v1.1 (2021-04-24)](#v11-2021-04-24)
+    * [v1.0 (2021-01-15)](#v10-2021-01-15)
+
+## Version history
+
+### v3.5.0 (2023-05-25)
+
+* `BS_thread_pool.hpp` and `BS_thread_pool_light.hpp`:
+    * Added a new member function, `purge()`, to the full (non-light) thread pool. This function purges all the tasks waiting in the queue. Tasks that are currently running will not be affected, but any tasks still waiting in the queue will be removed and will never be executed by the threads. Please note that there is no way to restore the purged tasks.
+    * Fix a bug which caused `wait_for_tasks()` to only block the first thread that called it. Now it blocks every thread that calls it, which is the expected behavior. In addition, all related deadlock have now been completely resolved. This also applies to the variants `wait_for_tasks_duration()` and `wait_for_tasks_until()` in the non-light version. See [#110](https://github.com/bshoshany/thread-pool/pull/110).
+        * Note: You should never call `wait_for_tasks()` from within a thread of the same thread pool, as that will cause it to wait forever! This fix is relevant for situations when `wait_for_tasks()` is called from an auxiliary `std::thread` or a separate thread pool.
+    * `push_task()` and `submit()` now avoid creating unnecessary copies of the function object. This should improve performance, especially if large objects are involved. See [#90](https://github.com/bshoshany/thread-pool/pull/90).
+    * Optimized the way condition variables are used by the thread pool class. Shared variables are now modified while owning the mutex, but condition variables are notified after the mutex is released, if possible. See [#84](https://github.com/bshoshany/thread-pool/pull/84).
+    * Instead of a variable `tasks_total` to keep track of the total number of tasks (queued + running), the thread pool class now uses a variable `tasks_running` to keep track only of the number of running tasks, with the number of tasks in the queue obtained via `tasks.size()`. This makes more sense in terms of the internal logic of the class.
+    * All atomic variables have been converted to non-atomic. They are now all governed by `tasks_mutex`, so they do not need to be atomic. This eliminates redundant locking, and may improve performance a bit.
+    * `running` has been renamed to `workers_running` and `task_done_cv` has been renamed to `tasks_done_cv`.
+    * The worker now only notifies thi condition variable `tasks_done_cv` if all the tasks are done, not just a single task. Checking if the tasks are done is cheaper than notifying the condition variable, so since the worker no longer notifies the condition variable every single time it finishes a task, this should improve performance a bit if `wait_for_tasks()` is used.
+* `BS_thread_pool_test.cpp`:
+    * Combined the tests for the full and light versions into one program. The file `BS_thread_pool_light_test.cpp` has been removed.
+    * The tests for the light version are now much more comprehensive. The only features that are not tested in the light version are those that do not exist in it.
+    * Added a test for the new `purge()` member function.
+    * Added a test to ensure that `push_task()` and `submit()` do not create unnecessary copies of the function object.
+    * Added a test to ensure that `push_task()` and `submit()` correctly accept arguments passed by value, reference, and constant reference.
+    * Added a test to ensure that `wait_for_tasks()` blocks all external threads that call it.
+    * `_CRT_SECURE_NO_WARNINGS` is now set only if it has not already been defined, to prevent errors in MSVC projects which already have it set as part of the default build settings. See [#72](https://github.com/bshoshany/thread-pool/pull/72).
+* `README.md`:
+    * Added documentation for the new `purge()` member function.
+    * Added an explanation for how to pass arguments by reference or constant reference when submitting functions to the queue, using the wrappers `std::ref()` and `std::cref()` respectively. See [#83](https://github.com/bshoshany/thread-pool/issues/83).
+    * Added a link to [my lecture notes](https://baraksh.com/CSE701/notes.php) for a course taught at McMaster University, for the benefit of beginner C++ programmers who wish to learn some of the advanced techniques and programming practices used in developing this library.
+    * Removed the sample test results, since the complete log file (including the deadlock tests) is now over 500 lines long.
+* Other:
+    * A `.clang-format` file with the project's formatting conventions is now included in the GitHub repository. The pull request template now asks to format any new code using this file, so that it is consistent with the rest of the library.
+    * A PowerShell script, `BS_thread_pool_test.ps1`, is now provided in the GitHub repository to make running the test on multiple compilers and operating systems easier. Since it is written in PowerShell, it is fully portable and works on Windows, Linux, and macOS. The script will automatically detect if Clang, GCC, and/or MSVC are available, compile the test program using each available compiler, and then run each compiled test program 5 times and report on any errors. The pull request template now recommends using this script for testing.
+    * Since the root folder has become a bit crowded, the header files `BS_thread_pool.hpp` and `BS_thread_pool_light.hpp` have been moved to the `include` subfolder, and the test file `BS_thread_pool_test.cpp` has been moved to the `tests` subfolder, which also contains the new test script `BS_thread_pool_test.ps1`.
+
+### v3.4.0 (2023-05-12)
+
+* `BS_thread_pool.hpp` and `BS_thread_pool_light.hpp`:
+    * Resolved an issue which could have caused `tasks_total` to not be synchronized in some cases. See [#70](https://github.com/bshoshany/thread-pool/pull/70).
+    * Resolved a deadlock which could rarely be caused when the pool was destructed or reset. See [#93](https://github.com/bshoshany/thread-pool/pull/93), [#100](https://github.com/bshoshany/thread-pool/pull/100), [#107](https://github.com/bshoshany/thread-pool/pull/107), and [#108](https://github.com/bshoshany/thread-pool/pull/108).
+    * Resolved a deadlock which could be caused when `wait_for_tasks()` was called more than once.
+    * Two new member functions have been added to the non-light version: `wait_for_tasks_duration()` and `wait_for_tasks_until()`. They allow waiting for the tasks to complete, but with a timeout. `wait_for_tasks_duration()` will stop waiting after the specified duration has passed, and `wait_for_tasks_until()` will stop waiting after the specified time point has been reached.
+    * Renamed `BS_THREAD_POOL_VERSION` in `BS_thread_pool_light.hpp` to `BS_THREAD_POOL_LIGHT_VERSION` and removed the `[light]` tag. This allows including both header files in the same program in case we want to use both the light and non-light thread pools simultaneously.
+* `BS_thread_pool_test.cpp` and `BS_thread_pool_light_test.cpp`:
+    * Fixed an issue that caused a compilation error when using MSVC and including `Windows.h`. See [#72](https://github.com/bshoshany/thread-pool/pull/72).
+    * The number and size of the vectors in the performance test (`BS_thread_pool_test.cpp` only) are now guaranteed to be multiples of the number of threads, for optimal performance.
+    * In `count_unique_threads()`, moved the condition variables and mutexes to the function scope to prevent cluttering the global scope.
+    * Three new tests have been added to `BS_thread_pool_test.cpp` to check the deadlocks issue that were resolved in this release (see above). The tests rely on the new wait for tasks with timeout feature, so they are not available in the light version.
+        * One test checks for deadlocks when calling `wait_for_tasks()` more than once.
+        * Two tests check for deadlocks when destructing and resetting the pool respectively. They are turned off by default, since they take a long time to complete, but can be turned on by setting `enable_long_deadlock_tests` to `true`.
+    * Two new tests have been added to the non-light version to check the new member functions `wait_for_tasks_duration()` and `wait_for_tasks_until()`.
+    * The test programs now return the number of failed tests upon exit, instead of just 1 if any number of tests failed, which was the case in previous versions. Also, if any tests failed, `std::quick_exit()` is invoked instead of `return`, to avoid getting stuck due to any lingering tasks or deadlocks.
+* `README.md`:
+    * Added documentation for the two new member functions, `wait_for_tasks_duration()` and `wait_for_tasks_until()`.
+    * Fixed Markdown rendering incorrectly on Visual Studio. See [#77](https://github.com/bshoshany/thread-pool/pull/77).
+    * The sample performance tests are now taken from a 40-core / 80-thread dual-CPU computing node, which is a more typical use case for high-performance scientific software.
+
+### v3.3.0 (2022-08-03)
+
+* `BS_thread_pool.hpp`:
+    * The public member variable `paused` of `BS::thread_pool` has been made private for future-proofing (in case future versions implement a more involved pausing mechanism) and better encapsulation. It is now accessible only via the `pause()`, `unpause()`, and `is_paused()` member functions. In other words:
+        * Replace `pool.paused = true` with `pool.pause()`.
+        * Replace `pool.paused = false` with `pool.unpause()`.
+        * Replace `if (pool.paused)` (or similar) with `if (pool.is_paused())`.
+    * The public member variable `f` of `BS::multi_future` has been renamed to `futures` for clarity, and has been made private for encapsulation and simplification purposes. Instead of operating on the vector `futures` itself, you can now use the `[]` operator of the `BS::multi_future` to access the future at a specific index directly, or the `push_back()` member function to append a new future to the list. The `size()` member function tells you how many futures are currently stored in the object.
+    * The explicit casts of `std::endl` and `std::flush`, added in v3.2.0 to enable flushing a `BS::synced_stream`, caused ODR (One Definition Rule) violations if `BS_thread_pool.hpp` was included in two different translation units, since they were mistakenly not defined as `inline`. To fix this, I decided to make them static members of `BS::synced_stream` instead of global variables, which also makes the code better organized in my opinion. These objects can now be accessed as `BS::synced_stream::endl` and `BS::synced_stream::flush`. I also added an example for how to use them in `README.md`. See [#64](https://github.com/bshoshany/thread-pool/issues/64).
+* `BS_thread_pool_light.hpp`:
+    * This package started out as a very lightweight thread pool, but over time has expanded to include many additional features, and at the time of writing it has a total of 340 lines of code, including all the helper classes. Therefore, I have decided to bundle a light version of the thread pool in a separate and stand-alone header file, `BS_thread_pool_light.hpp`, with only 170 lines of code (half the size of the full package). This file does not contain any of the helper classes, only a new `BS::thread_pool_light` class, which is a minimal thread pool with only the 5 most basic member functions:
+        * `get_thread_count()`
+        * `push_loop()`
+        * `push_task()`
+        * `submit()`
+        * `wait_for_tasks()`
+    * A separate test program `BS_thread_pool_light_test.cpp` tests only the features of the lightweight `BS::thread_pool_light` class. In the spirit of minimalism, it does not generate a log file and does not do any benchmarks.
+    * To be perfectly clear, each header file is 100% stand-alone. If you wish to use the full package, you only need `BS_thread_pool.hpp`, and if you wish to use the light version, you only need `BS_thread_pool_light.hpp`. Only a single header file needs to be included in your project.
+
+### v3.2.0 (2022-07-28)
+
+* `BS_thread_pool.hpp`:
+    * Main `BS::thread_pool` class:
+        * Added a new member function, `push_loop()`, which does the same thing as `parallelize_loop()`, except that it does not return a `BS::multi_future` with the futures for each block. Just like `push_task()` vs. `submit()`, this avoids the overhead of creating the futures, but the user must use `wait_for_tasks()` or some other method to ensure that the loop finishes executing, otherwise bad things will happen.
+        * `push_task()` and `submit()` now utilize perfect forwarding in order to support more types of tasks - in particular member functions, which in previous versions could not be submitted unless wrapped in a lambda. To submit a member function, use the syntax `submit(&class::function, &object, args)`. More information can be found in `README.md`. See [#9](https://github.com/bshoshany/thread-pool/issues/9).
+        * `push_loop()` and `parallelize_loop()` now have overloads where the first argument (the first index in the loop) is omitted, in which case it is assumed to be 0. This is for convenience, as the case where the first index is 0 is very common.
+    * Helper classes:
+        * `BS::synced_stream` now utilizes perfect forwarding in the member functions `print()` and `println()`.
+        * Previously, it was impossible to pass the flushing manipulators `std::endl` and `std::flush` to `print()` and `println()`, since the compiler could not figure out which template specializations to use. The new objects `BS::endl` and `BS::flush` are explicit casts of these manipulators, whose sole purpose is to enable passing them to `print()` and `println()`.
+        * `BS::multi_future::get()` now rethrows exceptions generated by the futures, even if the futures return `void`. See [#62](https://github.com/bshoshany/thread-pool/pull/62).
+        * Added a new helper class, `BS::blocks`, which is used by `parallelize_loop()` and `push_loop()` to divide a range into blocks. This class is not documented in `README.md`, as it most likely will not be of interest to most users, but it is still publicly available, in case you want to parallelize something manually but still benefit from the built-in algorithm for splitting a range into blocks.
+* `BS_thread_pool_test.cpp`:
+    * Added plenty of new tests for the new features described above.
+    * Fixed a bug in `count_unique_threads()` that caused it to get stuck on certain systems.
+    * `dual_println()` now also flushes the stream using `BS::endl`, so that if the test gets stuck, the log file will still contain everything up to that point. (Note: It is a common misconception that `std::endl` and `'\n'` are interchangeable. `std::endl` not only prints a newline character, it also flushes the stream, which is not always desirable, as it may reduce performance.)
+    * The performance test has been modified as follows:
+        * Instead of generating random vectors using `std::mersenne_twister_engine`, which proved to be inconsistent across different compilers and systems, the test now generates each element via an arbitrarily-chosen numerical operation. In my testing, this provided much more consistent results.
+        * Instead of using a hard-coded vector size, a suitable vector size is now determined dynamically at runtime.
+        * Instead of using `parallelize_loop()`, the test now uses the new `push_loop()` function to squeeze out a bit more performance.
+        * Instead of setting the test parameters to achieve a fixed single-threaded mean execution time of 300 ms, the test now aims to achieve a fixed multi-threaded mean execution time of 50 ms when the number of blocks is equal to the number of threads. This allows for more reliable results on very fast CPUs with a very large number of threads, where the mean execution time when using all the threads could previously be below a statistically significant value.
+        * The number of vectors is now restricted to be a multiple of the number of threads, so that the blocks are always all of the same size.
+* `README.md`:
+    * Added instructions and examples for the new features described above.
+    * Rewrote the documentation for `parallelize_loop()` to make it clearer.
+
+### v3.1.0 (2022-07-13)
+
+* `BS_thread_pool.hpp`:
+    * Fixed an issue where `wait_for_tasks()` would sometimes get stuck if `push_task()` was executed immediately before `wait_for_tasks()`.
+    * Both the thread pool constructor and the `reset()` member function now determine the number of threads to use in the pool as follows. If the parameter is a positive number, then the pool will be created with this number of threads. If the parameter is non-positive, or a parameter was not supplied, then the pool will be created with the total number of hardware threads available, as obtained from `std::thread::hardware_concurrency()`. If the latter returns a non-positive number for some reason, then the pool will be created with just one thread. See [#51](https://github.com/bshoshany/thread-pool/issues/51) and [#52](https://github.com/bshoshany/thread-pool/issues/52).
+    * Added the `[[nodiscard]]` attribute to classes and class members, in order to warn the user when accidentally discarding an important return value, such as a future or the return value of a function with no useful side-effects. For example, if you use `submit()` and don't save the future it returns, the compiler will now generate a warning. (If a future is not needed, then you should use `push_task()` instead.)
+    * Removed the `explicit` specifier from all constructors, as it prevented the default constructor from being used with static class members. See [#48](https://github.com/bshoshany/thread-pool/issues/48>).
+* `BS_thread_pool_test.cpp`:
+    * Improved `count_unique_threads()` using condition variables, to ensure that each thread in the pool runs at least one task regardless of how fast it takes to run the tasks.
+    * When appropriate, `check()` now explicitly reports what the obtained result was and what it was expected to be.
+    * `check_task_monitoring()` and `check_pausing()` now explicitly report the results of the monitoring at each step.
+    * Changed all instances of `std::vector<std::atomic<bool>>` to `std::unique_ptr<std::atomic<bool>[]>`. See [#44](https://github.com/bshoshany/thread-pool/issues/44).
+    * Converted a few more C-style casts to C++ cast expressions.
+* `README.md`:
+    * Added instructions for using this package with the [Conan](https://conan.io/) C/C++ package manager. Please refer to [this package's page on ConanCenter](https://conan.io/center/bshoshany-thread-pool) to learn how to use Conan to include this package in your project with various build systems.
+* If you found this project useful, please consider [starring it on GitHub](https://github.com/bshoshany/thread-pool/stargazers)! This allows me to see how many people are using my code, and motivates me to keep working to improve it.
+
+### v3.0.0 (2022-05-30)
+
+* This is a major new release with many changes and improvements! Please note that code written using previous releases will need to be slightly modified to work with the new release. The changes needed to migrate to the new API are explicitly indicated below for your convenience.
+* Breaking changes to the library header file:
+    * The header file has been renamed to `BS_thread_pool.hpp` to avoid potential conflict with other thread pool libraries.
+        * **API migration:** The library must now be included by invoking `#include "BS_thread_pool.hpp"`.
+    * All the definitions in the library, including the `thread_pool` class and the helper classes, are now located in the namespace `BS`. This namespace will also be used for my other C++ projects, and is intended to ensure consistency between my projects while avoiding potential name conflicts with other libraries.
+        * **API migration:** The thread pool class should now be invoked as `BS::thread_pool`. Alternatively, it is possible to employ `using BS::thread_pool` or even `using namespace BS` and then invoke `thread_pool` directly. Same for the `BS::synced_stream` and `BS::timer` helper classes.
+    * The macro `THREAD_POOL_VERSION`, which contains the version number and release date of the library, has been renamed to `BS_THREAD_POOL_VERSION` to avoid potential conflicts.
+        * **API migration:** The version must now be read from the macro `BS_THREAD_POOL_VERSION`.
+    * The public member `sleep_duration` has been removed. The thread pool now uses condition variables instead of sleep to facilitate waiting. This significantly improves performance (by 10%-50% in my testing), drastically decreases idle CPU utilization, and eliminates the need to set an optimal sleep time. This was a highly-requested change; see [issue #1](https://github.com/bshoshany/thread-pool/issues/1), [issue #12](https://github.com/bshoshany/thread-pool/issues/12), and [pull request #23](https://github.com/bshoshany/thread-pool/pull/23).
+        * **API migration:** Remove any code that relates to the public member `sleep_duration`.
+    * The template specializations for `submit()` have been merged. Now instead of two versions, one for functions with a return value and one for functions without a return value, there is just one version, which can accept any function. This makes the code more compact (and elegant). If a function with no return value is submitted, an `std::future<void>` is returned (the previous version returned an `std::future<bool>`)
+        * **API migration:** To wait for a task with no return value, simply call `wait()` or `get()` on the corresponding `std::future<void>`.
+    * `parallelize_loop()` now returns a future in the form of a new `BS::multi_future` helper class template. The member function `wait()` of this future allows waiting until all of the loop's blocks finish executing. In previous versions, calling `parallelize_loop()` both parallelized the loop and waited for the blocks to finish; now it is possible to do other stuff while the loop executes.
+        * **API migration:** Since `parallelize_loop()` no longer automatically blocks, you should either store the result in a `BS::multi_future` object and call its `wait()` member function, or simply call `parallelize_loop().wait()` to reproduce the old behavior.
+* Non-breaking changes to the library header file:
+    * It is now possible to use `parallelize_loop()` with functions that have return values and get these values from all blocks at once through the `get()` member function of the `BS::multi_future`.
+    * The template specializations for `push_task()` have been merged. Now instead of two versions, one for functions with arguments and one for functions without arguments, there is just one version, which can accept any function.
+    * Constructors have been made `explicit`. See [issue #28](https://github.com/bshoshany/thread-pool/issues/28).
+    * `submit()` now uses `std::make_shared` instead of `new` to create the shared pointer. This means only one memory allocation is performed instead of two, which should improve performance. In addition, all unique pointers are now created using `std::make_unique`.
+    * A new helper class template, `BS::multi_future`, has been added. It's basically just a wrapper around `std::vector<std::future<T>>`. This class is used by the new implementation of `parallelize_loop()` to allow waiting for the entire loop, consisting of multiple tasks with their corresponding futures, to finish executing.
+    * `BS::multi_future` can also be used independently to handle multiple futures at once. For example, you can now keep track of several groups of tasks by storing their futures inside separate `BS::multi_future` objects and use either `wait()` to wait for all tasks in a specific group to finish or `get()` to get an `std::vector` with the return values of every task in the group.
+    * Integer types are now chosen in a smarter way to improve portability, allow for better compatibility with 32-bit systems, and prevent potential conversion errors.
+    * Added a new type, `BS::concurrency_t`, equal to the return type of `std::thread::hardware_concurrency()`. This is probably pointless, since the C++ standard requires this to be `unsigned int`, but it seems to me to make the code slightly more portable, in case some non-conforming compiler chooses to use a different integer type.
+    * C-style casts have been converted to C++ cast expressions for added clarity.
+    * Miscellaneous minor optimizations and style improvements.
+* Changes to the test program:
+    * The program has been renamed to `BS_thread_pool_test.cpp` to avoid potential conflict with other thread pool libraries.
+    * The program now returns `EXIT_FAILURE` if any of the tests failed, for automation purposes. See [pull request #42](https://github.com/bshoshany/thread-pool/pull/42).
+    * Fixed incorrect check order in `check_task_monitoring()`. See [pull request #43](https://github.com/bshoshany/thread-pool/pull/43).
+    * Added a new test for `parallelize_loop()` with a return value.
+    * Improved some of the tests to make them more reliable. For example, `count_unique_threads()` now uses futures (stored in a `BS::multi_future<void>` object).
+    * The program now uses `std::vector` instead of matrices, for both consistency checks and benchmarks, in order to simplify the code and considerably reduce its length.
+    * The benchmarks have been simplified. There's now only one test: filling a specific number of vectors of fixed size with random values. This may be replaced with something more practical in a future released, but at least on the systems I've tested on, it does demonstrate a very significant multi-threading speedup.
+    * In addition to multi-threaded tests with different numbers of tasks, the benchmark now also includes a single-threaded test. This allows for more accurate benchmarks compared to previous versions, as the (slight) parallelization overhead is now taken into account when calculating the maximum speedup.
+    * The program decides how many vectors to use for benchmarking by testing how many are needed to reach a target duration in the single-threaded test. This ensures that the test takes approximately the same amount of time on different systems, and is thus more consistent and portable.
+    * Miscellaneous minor optimizations and style improvements.
+* Changes to `README.md`:
+    * Many sections have been rewritten and/or polished.
+    * Explanations and examples of all the new features have been added.
+    * Added an acknowledgements section.
+* Miscellaneous changes:
+    * Added a `CITATION.bib` file (in BibTeX format) to the GitHub repository. You can use it to easily cite this package if you use it in any research papers.
+    * Added a `CITATION.cff` file (in YAML format) to the GitHub repository. This should add [an option to get a citation in different formats](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-citation-files) directly from GitHub repository by clicking on "cite this repository" on the sidebar to the right.
+    * Added templates for GitHub issues and pull requests.
+
+### v2.0.0 (2021-08-14)
+
+* From now on, version numbers will adhere to the [Semantic Versioning](https://semver.org/) specification in the format **major.minor.patch**.
+* A file named `thread_pool_test.cpp` has been added to the package. It will perform automated tests of all aspects of the package, and benchmark some multithreaded matrix operations. Please run it on your system and [submit a bug report](https://github.com/bshoshany/thread-pool/issues) if any of the tests fail. In addition, the code is thoroughly documented, and is meant to serve as an extensive example of how to properly use the package.
+* The package is now available through [vcpkg](https://github.com/microsoft/vcpkg). Instructions for how to install it have been added to `README.md`. See [this pull request](https://github.com/bshoshany/thread-pool/pull/18).
+* The package now defines a macro `THREAD_POOL_VERSION`, which returns the version number and release date of the thread pool library as a string.
+* `parallelize_loop()` has undergone some major changes (and is now incompatible with v1.x):
+    * The second argument is now the index **after** the last index, instead of the last index itself. This is more consistent with C++ conventions (e.g. standard library algorithms) where the range is always `[first, last)`. For example, for an array with `n` indices, instead of `parallelize_loop(0, n - 1, ...)` you should now write `parallelize_loop(0, n, ...)`.
+    * The `loop` function is now only called once per block, instead of once per index, as was the case before. This should provide a performance boost due to significantly reducing the number of function calls, and it also allows you to conserve resources by using them only once per block instead of once per index (an example can be found in the `random_matrix_generator` class in `thread_pool_test.cpp`). It also means that `loop` now takes two arguments: the first index in the block and the index after the last index in the block. Thus, `loop(start, end)` should typically involve a loop of the form `for (T i = start; i < end; i++)`.
+    * The first and last indices can now be of two different integer types. Previously, `parallelize_loop(0, i, ...)` did not work if `i` was not an `int`, because `0` was interpreted as `int`, and the two arguments had to be of the same type. Therefore, one had to use casting, e.g. `parallelize_loop((size_t)0, i)`, to make it work. Now this is no longer necessary; the common type is inferred automatically using `std::common_type_t`.
+
+### v1.9 (2021-07-29)
+
+* Fixed a bug in `reset()` which caused it to create the wrong number of threads.
+
+### v1.8 (2021-07-28)
+
+* The version history has become too long to be included in `README.md`, so I moved it to a separate file, `CHANGELOG.md`.
+* A button to open this repository directly in Visual Studio Code has been added to the badges in `README.md`.
+* An internal variable named `promise` has been renamed to `task_promise` to avoid any potential errors in case the user invokes `using namespace std`.
+* `submit()` now catches exceptions thrown by the submitted task and forwards them to the future. See [this issue](https://github.com/bshoshany/thread-pool/issues/14).
+* Eliminated compiler warnings that appeared when using the `-Weffc++` flag in GCC. See [this pull request](https://github.com/bshoshany/thread-pool/pull/17).
+
+### v1.7 (2021-06-02)
+
+* Fixed a bug in `parallelize_loop()` which prevented it from actually running loops in parallel, see [this issue](https://github.com/bshoshany/thread-pool/issues/11).
+
+### v1.6 (2021-05-26)
+
+* Since MSVC does not interpret `and` as `&&` by default, the previous release did not compile with MSVC unless the `/permissive-` or `/Za` compiler flags were used. This has been fixed in this version, and the code now successfully compiles with GCC, Clang, and MSVC. See [this pull request](https://github.com/bshoshany/thread-pool/pull/10).
+
+### v1.5 (2021-05-07)
+
+* This library now has a DOI for citation purposes. Information on how to cite it in publications has been added to the source code and to `README.md`.
+* Added GitHub badges to `README.md`.
+
+### v1.4 (2021-05-05)
+
+* Added three new public member functions to monitor the tasks submitted to the pool:
+    * `get_tasks_queued()` gets the number of tasks currently waiting in the queue to be executed by the threads.
+    * `get_tasks_running()` gets the number of tasks currently being executed by the threads.
+    * `get_tasks_total()` gets the total number of unfinished tasks - either still in the queue, or running in a thread.
+    * Note that `get_tasks_running() == get_tasks_total() - get_tasks_queued()`.
+    * Renamed the private member variable `tasks_waiting` to `tasks_total` to make its purpose clearer.
+* Added an option to temporarily pause the workers:
+    * When public member variable `paused` is set to `true`, the workers temporarily stop popping new tasks out of the queue, although any tasks already executed will keep running until they are done. Set to `false` again to resume popping tasks.
+    * While the workers are paused, `wait_for_tasks()` will wait for the running tasks instead of all tasks (otherwise it would wait forever).
+    * By utilizing the new pausing mechanism, `reset()` can now change the number of threads on-the-fly while there are still tasks waiting in the queue. The new thread pool will resume executing tasks from the queue once it is created.
+* `parallelize_loop()` and `wait_for_tasks()` now have the same behavior as the worker function with regards to waiting for tasks to complete. If the relevant tasks are not yet complete, then before checking again, they will sleep for `sleep_duration` microseconds, unless that variable is set to zero, in which case they will call `std::this_thread::yield()`. This should improve performance and reduce CPU usage.
+* Merged [this commit](https://github.com/bshoshany/thread-pool/pull/8): Fixed weird error when using MSVC and including `windows.h`.
+* The `README.md` file has been reorganized and expanded.
+
+### v1.3 (2021-05-03)
+
+* Fixed [this issue](https://github.com/bshoshany/thread-pool/issues/3): Removed `std::move` from the `return` statement in `push_task()`. This previously generated a `-Wpessimizing-move` warning in Clang. The assembly code generated by the compiler seems to be the same before and after this change, presumably because the compiler eliminates the `std::move` automatically, but this change gets rid of the Clang warning.
+* Fixed [this issue](https://github.com/bshoshany/thread-pool/issues/5): Removed a debugging message printed to `std::cout`, which was left in the code by mistake.
+* Fixed [this issue](https://github.com/bshoshany/thread-pool/issues/6): `parallelize_loop()` no longer sends references for the variables `start` and `stop` when calling `push_task()`, which may lead to undefined behavior.
+* A companion paper is now published at <a href="https://arxiv.org/abs/2105.00613">arXiv:2105.00613</a>, including additional information such as performance tests on systems with up to 80 hardware threads. The `README.md` has been updated, and it is now roughly identical in content to the paper.
+
+### v1.2 (2021-04-29)
+
+* The worker function, which controls the execution of tasks by each thread, now sleeps by default instead of yielding. Previously, when the worker could not find any tasks in the queue, it called `std::this_thread::yield()` and then tried again. However, this caused the workers to have high CPU usage when idle, [as reported by some users](https://github.com/bshoshany/thread-pool/issues/1). Now, when the worker function cannot find a task to run, it instead sleeps for a duration given by the public member variable `sleep_duration` (in microseconds) before checking the queue again. The default value is `1000` microseconds, which I found to be optimal in terms of both CPU usage and performance, but your own optimal value may be different.
+* If the constructor is called with an argument of zero for the number of threads, then the default value, `std::thread::hardware_concurrency()`, is used instead.
+* Added a simple helper class, `timer`, which can be used to measure execution time for benchmarking purposes.
+* Improved and expanded the documentation.
+
+### v1.1 (2021-04-24)
+
+* Cosmetic changes only. Fixed a typo in the Doxygen comments and added a link to the GitHub repository.
+
+### v1.0 (2021-01-15)
+
+* Initial release.

CITATION.bib

@@ -0,0 +1,13 @@
+@article{Shoshany2021_ThreadPool,
+    archiveprefix = {arXiv},
+    author        = {Barak Shoshany},
+    doi           = {10.5281/zenodo.4742687},
+    eid           = {arXiv:2105.00613},
+    eprint        = {2105.00613},
+    journal       = {arXiv e-prints},
+    keywords      = {Computer Science - Distributed, Parallel, and Cluster Computing, D.1.3, D.1.5},
+    month         = {May},
+    primaryclass  = {cs.DC},
+    title         = {{A C++17 Thread Pool for High-Performance Scientific Computing}},
+    year          = {2021}
+}

CITATION.cff

@@ -0,0 +1,24 @@
+---
+authors:
+    - family-names: "Shoshany"
+      given-names: "Barak"
+      orcid: "https://orcid.org/0000-0003-2222-127X"
+cff-version: "1.2.0"
+date-released: "2021-05-03"
+doi: "10.5281/zenodo.4742687"
+license: "MIT"
+message: "If you use this package in published research, please cite it as follows."
+repository-code: "https://github.com/bshoshany/thread-pool"
+title: "A C++17 Thread Pool for High-Performance Scientific Computing"
+preferred-citation:
+    type: "article"
+    authors:
+        - family-names: "Shoshany"
+          given-names: "Barak"
+          orcid: "https://orcid.org/0000-0003-2222-127X"
+    doi: "10.5281/zenodo.4742687"
+    journal: "arXiv"
+    month: 5
+    title: "A C++17 Thread Pool for High-Performance Scientific Computing"
+    url: "https://arxiv.org/abs/2105.00613"
+    year: 2021

LICENSE.txt

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2021 Barak Shoshany
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2023 Barak Shoshany
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

include/BS_thread_pool.hpp

@@ -0,0 +1,819 @@
+#pragma once
+
+/**
+ * @file BS_thread_pool.hpp
+ * @author Barak Shoshany (baraksh@gmail.com) (http://baraksh.com)
+ * @version 3.5.0
+ * @date 2023-05-25
+ * @copyright Copyright (c) 2023 Barak Shoshany. Licensed under the MIT license. If you found this project useful, please consider starring it on GitHub! If you use this library in software of any kind, please provide a link to the GitHub repository https://github.com/bshoshany/thread-pool in the source code and documentation. If you use this library in published research, please cite it as follows: Barak Shoshany, "A C++17 Thread Pool for High-Performance Scientific Computing", doi:10.5281/zenodo.4742687, arXiv:2105.00613 (May 2021)
+ *
+ * @brief BS::thread_pool: a fast, lightweight, and easy-to-use C++17 thread pool library. This header file contains the entire library, including the main BS::thread_pool class and the helper classes BS::multi_future, BS::blocks, BS:synced_stream, and BS::timer.
+ */
+
+#define BS_THREAD_POOL_VERSION "v3.5.0 (2023-05-25)"
+
+#include <chrono>             // std::chrono
+#include <condition_variable> // std::condition_variable
+#include <exception>          // std::current_exception
+#include <functional>         // std::bind, std::function, std::invoke
+#include <future>             // std::future, std::promise
+#include <iostream>           // std::cout, std::endl, std::flush, std::ostream
+#include <memory>             // std::make_shared, std::make_unique, std::shared_ptr, std::unique_ptr
+#include <mutex>              // std::mutex, std::scoped_lock, std::unique_lock
+#include <queue>              // std::queue
+#include <thread>             // std::thread
+#include <type_traits>        // std::common_type_t, std::conditional_t, std::decay_t, std::invoke_result_t, std::is_void_v
+#include <utility>            // std::forward, std::move, std::swap
+#include <vector>             // std::vector
+
+namespace BS
+{
+/**
+ * @brief A convenient shorthand for the type of std::thread::hardware_concurrency(). Should evaluate to unsigned int.
+ */
+using concurrency_t = std::invoke_result_t<decltype(std::thread::hardware_concurrency)>;
+
+// ============================================================================================= //
+//                                    Begin class multi_future                                   //
+
+/**
+ * @brief A helper class to facilitate waiting for and/or getting the results of multiple futures at once.
+ *
+ * @tparam T The return type of the futures.
+ */
+template <typename T>
+class [[nodiscard]] multi_future
+{
+public:
+    /**
+     * @brief Construct a multi_future object with the given number of futures.
+     *
+     * @param num_futures_ The desired number of futures to store.
+     */
+    multi_future(const size_t num_futures_ = 0) : futures(num_futures_) {}
+
+    /**
+     * @brief Get the results from all the futures stored in this multi_future object, rethrowing any stored exceptions.
+     *
+     * @return If the futures return void, this function returns void as well. Otherwise, it returns a vector containing the results.
+     */
+    [[nodiscard]] std::conditional_t<std::is_void_v<T>, void, std::vector<T>> get()
+    {
+        if constexpr (std::is_void_v<T>)
+        {
+            for (size_t i = 0; i < futures.size(); ++i)
+                futures[i].get();
+            return;
+        }
+        else
+        {
+            std::vector<T> results(futures.size());
+            for (size_t i = 0; i < futures.size(); ++i)
+                results[i] = futures[i].get();
+            return results;
+        }
+    }
+
+    /**
+     * @brief Get a reference to one of the futures stored in this multi_future object.
+     *
+     * @param i The index of the desired future.
+     * @return The future.
+     */
+    [[nodiscard]] std::future<T>& operator[](const size_t i)
+    {
+        return futures[i];
+    }
+
+    /**
+     * @brief Append a future to this multi_future object.
+     *
+     * @param future The future to append.
+     */
+    void push_back(std::future<T> future)
+    {
+        futures.push_back(std::move(future));
+    }
+
+    /**
+     * @brief Get the number of futures stored in this multi_future object.
+     *
+     * @return The number of futures.
+     */
+    [[nodiscard]] size_t size() const
+    {
+        return futures.size();
+    }
+
+    /**
+     * @brief Wait for all the futures stored in this multi_future object.
+     */
+    void wait() const
+    {
+        for (size_t i = 0; i < futures.size(); ++i)
+            futures[i].wait();
+    }
+
+private:
+    /**
+     * @brief A vector to store the futures.
+     */
+    std::vector<std::future<T>> futures;
+};
+
+//                                     End class multi_future                                    //
+// ============================================================================================= //
+
+// ============================================================================================= //
+//                                       Begin class blocks                                      //
+
+/**
+ * @brief A helper class to divide a range into blocks. Used by parallelize_loop() and push_loop().
+ *
+ * @tparam T1 The type of the first index in the range. Should be a signed or unsigned integer.
+ * @tparam T2 The type of the index after the last index in the range. Should be a signed or unsigned integer. If T1 is not the same as T2, a common type will be automatically inferred.
+ * @tparam T The common type of T1 and T2.
+ */
+template <typename T1, typename T2, typename T = std::common_type_t<T1, T2>>
+class [[nodiscard]] blocks
+{
+public:
+    /**
+     * @brief Construct a blocks object with the given specifications.
+     *
+     * @param first_index_ The first index in the range.
+     * @param index_after_last_ The index after the last index in the range.
+     * @param num_blocks_ The desired number of blocks to divide the range into.
+     */
+    blocks(const T1 first_index_, const T2 index_after_last_, const size_t num_blocks_) : first_index(static_cast<T>(first_index_)), index_after_last(static_cast<T>(index_after_last_)), num_blocks(num_blocks_)
+    {
+        if (index_after_last < first_index)
+            std::swap(index_after_last, first_index);
+        total_size = static_cast<size_t>(index_after_last - first_index);
+        block_size = static_cast<size_t>(total_size / num_blocks);
+        if (block_size == 0)
+        {
+            block_size = 1;
+            num_blocks = (total_size > 1) ? total_size : 1;
+        }
+    }
+
+    /**
+     * @brief Get the first index of a block.
+     *
+     * @param i The block number.
+     * @return The first index.
+     */
+    [[nodiscard]] T start(const size_t i) const
+    {
+        return static_cast<T>(i * block_size) + first_index;
+    }
+
+    /**
+     * @brief Get the index after the last index of a block.
+     *
+     * @param i The block number.
+     * @return The index after the last index.
+     */
+    [[nodiscard]] T end(const size_t i) const
+    {
+        return (i == num_blocks - 1) ? index_after_last : (static_cast<T>((i + 1) * block_size) + first_index);
+    }
+
+    /**
+     * @brief Get the number of blocks. Note that this may be different than the desired number of blocks that was passed to the constructor.
+     *
+     * @return The number of blocks.
+     */
+    [[nodiscard]] size_t get_num_blocks() const
+    {
+        return num_blocks;
+    }
+
+    /**
+     * @brief Get the total number of indices in the range.
+     *
+     * @return The total number of indices.
+     */
+    [[nodiscard]] size_t get_total_size() const
+    {
+        return total_size;
+    }
+
+private:
+    /**
+     * @brief The size of each block (except possibly the last block).
+     */
+    size_t block_size = 0;
+
+    /**
+     * @brief The first index in the range.
+     */
+    T first_index = 0;
+
+    /**
+     * @brief The index after the last index in the range.
+     */
+    T index_after_last = 0;
+
+    /**
+     * @brief The number of blocks.
+     */
+    size_t num_blocks = 0;
+
+    /**
+     * @brief The total number of indices in the range.
+     */
+    size_t total_size = 0;
+};
+
+//                                        End class blocks                                       //
+// ============================================================================================= //
+
+// ============================================================================================= //
+//                                    Begin class thread_pool                                    //
+
+/**
+ * @brief A fast, lightweight, and easy-to-use C++17 thread pool class.
+ */
+class [[nodiscard]] thread_pool
+{
+public:
+    // ============================
+    // Constructors and destructors
+    // ============================
+
+    /**
+     * @brief Construct a new thread pool.
+     *
+     * @param thread_count_ The number of threads to use. The default value is the total number of hardware threads available, as reported by the implementation. This is usually determined by the number of cores in the CPU. If a core is hyperthreaded, it will count as two threads.
+     */
+    thread_pool(const concurrency_t thread_count_ = 0) : thread_count(determine_thread_count(thread_count_)), threads(std::make_unique<std::thread[]>(determine_thread_count(thread_count_)))
+    {
+        create_threads();
+    }
+
+    /**
+     * @brief Destruct the thread pool. Waits for all tasks to complete, then destroys all threads. Note that if the pool is paused, then any tasks still in the queue will never be executed.
+     */
+    ~thread_pool()
+    {
+        wait_for_tasks();
+        destroy_threads();
+    }
+
+    // =======================
+    // Public member functions
+    // =======================
+
+    /**
+     * @brief Get the number of tasks currently waiting in the queue to be executed by the threads.
+     *
+     * @return The number of queued tasks.
+     */
+    [[nodiscard]] size_t get_tasks_queued() const
+    {
+        const std::scoped_lock tasks_lock(tasks_mutex);
+        return tasks.size();
+    }
+
+    /**
+     * @brief Get the number of tasks currently being executed by the threads.
+     *
+     * @return The number of running tasks.
+     */
+    [[nodiscard]] size_t get_tasks_running() const
+    {
+        const std::scoped_lock tasks_lock(tasks_mutex);
+        return tasks_running;
+    }
+
+    /**
+     * @brief Get the total number of unfinished tasks: either still waiting in the queue, or running in a thread. Note that get_tasks_total() == get_tasks_queued() + get_tasks_running().
+     *
+     * @return The total number of tasks.
+     */
+    [[nodiscard]] size_t get_tasks_total() const
+    {
+        const std::scoped_lock tasks_lock(tasks_mutex);
+        return tasks_running + tasks.size();
+    }
+
+    /**
+     * @brief Get the number of threads in the pool.
+     *
+     * @return The number of threads.
+     */
+    [[nodiscard]] concurrency_t get_thread_count() const
+    {
+        return thread_count;
+    }
+
+    /**
+     * @brief Check whether the pool is currently paused.
+     *
+     * @return true if the pool is paused, false if it is not paused.
+     */
+    [[nodiscard]] bool is_paused() const
+    {
+        const std::scoped_lock tasks_lock(tasks_mutex);
+        return paused;
+    }
+
+    /**
+     * @brief Parallelize a loop by automatically splitting it into blocks and submitting each block separately to the queue. Returns a multi_future object that contains the futures for all of the blocks.
+     *
+     * @tparam F The type of the function to loop through.
+     * @tparam T1 The type of the first index in the loop. Should be a signed or unsigned integer.
+     * @tparam T2 The type of the index after the last index in the loop. Should be a signed or unsigned integer. If T1 is not the same as T2, a common type will be automatically inferred.
+     * @tparam T The common type of T1 and T2.
+     * @tparam R The return value of the loop function F (can be void).
+     * @param first_index The first index in the loop.
+     * @param index_after_last The index after the last index in the loop. The loop will iterate from first_index to (index_after_last - 1) inclusive. In other words, it will be equivalent to "for (T i = first_index; i < index_after_last; ++i)". Note that if index_after_last == first_index, no blocks will be submitted.
+     * @param loop The function to loop through. Will be called once per block. Should take exactly two arguments: the first index in the block and the index after the last index in the block. loop(start, end) should typically involve a loop of the form "for (T i = start; i < end; ++i)".
+     * @param num_blocks The maximum number of blocks to split the loop into. The default is to use the number of threads in the pool.
+     * @return A multi_future object that can be used to wait for all the blocks to finish. If the loop function returns a value, the multi_future object can also be used to obtain the values returned by each block.
+     */
+    template <typename F, typename T1, typename T2, typename T = std::common_type_t<T1, T2>, typename R = std::invoke_result_t<std::decay_t<F>, T, T>>
+    [[nodiscard]] multi_future<R> parallelize_loop(const T1 first_index, const T2 index_after_last, F&& loop, const size_t num_blocks = 0)
+    {
+        blocks blks(first_index, index_after_last, num_blocks ? num_blocks : thread_count);
+        if (blks.get_total_size() > 0)
+        {
+            multi_future<R> mf(blks.get_num_blocks());
+            for (size_t i = 0; i < blks.get_num_blocks(); ++i)
+                mf[i] = submit(std::forward<F>(loop), blks.start(i), blks.end(i));
+            return mf;
+        }
+        else
+        {
+            return multi_future<R>();
+        }
+    }
+
+    /**
+     * @brief Parallelize a loop by automatically splitting it into blocks and submitting each block separately to the queue. Returns a multi_future object that contains the futures for all of the blocks. This overload is used for the special case where the first index is 0.
+     *
+     * @tparam F The type of the function to loop through.
+     * @tparam T The type of the loop indices. Should be a signed or unsigned integer.
+     * @tparam R The return value of the loop function F (can be void).
+     * @param index_after_last The index after the last index in the loop. The loop will iterate from 0 to (index_after_last - 1) inclusive. In other words, it will be equivalent to "for (T i = 0; i < index_after_last; ++i)". Note that if index_after_last == 0, no blocks will be submitted.
+     * @param loop The function to loop through. Will be called once per block. Should take exactly two arguments: the first index in the block and the index after the last index in the block. loop(start, end) should typically involve a loop of the form "for (T i = start; i < end; ++i)".
+     * @param num_blocks The maximum number of blocks to split the loop into. The default is to use the number of threads in the pool.
+     * @return A multi_future object that can be used to wait for all the blocks to finish. If the loop function returns a value, the multi_future object can also be used to obtain the values returned by each block.
+     */
+    template <typename F, typename T, typename R = std::invoke_result_t<std::decay_t<F>, T, T>>
+    [[nodiscard]] multi_future<R> parallelize_loop(const T index_after_last, F&& loop, const size_t num_blocks = 0)
+    {
+        return parallelize_loop(0, index_after_last, std::forward<F>(loop), num_blocks);
+    }
+
+    /**
+     * @brief Pause the pool. The workers will temporarily stop retrieving new tasks out of the queue, although any tasks already executed will keep running until they are finished.
+     */
+    void pause()
+    {
+        const std::scoped_lock tasks_lock(tasks_mutex);
+        paused = true;
+    }
+
+    /**
+     * @brief Purge all the tasks waiting in the queue. Tasks that are currently running will not be affected, but any tasks still waiting in the queue will be discarded, and will never be executed by the threads. Please note that there is no way to restore the purged tasks.
+     */
+    void purge()
+    {
+        const std::scoped_lock tasks_lock(tasks_mutex);
+        while (!tasks.empty())
+            tasks.pop();
+    }
+
+    /**
+     * @brief Parallelize a loop by automatically splitting it into blocks and submitting each block separately to the queue. Does not return a multi_future, so the user must use wait_for_tasks() or some other method to ensure that the loop finishes executing, otherwise bad things will happen.
+     *
+     * @tparam F The type of the function to loop through.
+     * @tparam T1 The type of the first index in the loop. Should be a signed or unsigned integer.
+     * @tparam T2 The type of the index after the last index in the loop. Should be a signed or unsigned integer. If T1 is not the same as T2, a common type will be automatically inferred.
+     * @tparam T The common type of T1 and T2.
+     * @param first_index The first index in the loop.
+     * @param index_after_last The index after the last index in the loop. The loop will iterate from first_index to (index_after_last - 1) inclusive. In other words, it will be equivalent to "for (T i = first_index; i < index_after_last; ++i)". Note that if index_after_last == first_index, no blocks will be submitted.
+     * @param loop The function to loop through. Will be called once per block. Should take exactly two arguments: the first index in the block and the index after the last index in the block. loop(start, end) should typically involve a loop of the form "for (T i = start; i < end; ++i)".
+     * @param num_blocks The maximum number of blocks to split the loop into. The default is to use the number of threads in the pool.
+     */
+    template <typename F, typename T1, typename T2, typename T = std::common_type_t<T1, T2>>
+    void push_loop(const T1 first_index, const T2 index_after_last, F&& loop, const size_t num_blocks = 0)
+    {
+        blocks blks(first_index, index_after_last, num_blocks ? num_blocks : thread_count);
+        if (blks.get_total_size() > 0)
+        {
+            for (size_t i = 0; i < blks.get_num_blocks(); ++i)
+                push_task(std::forward<F>(loop), blks.start(i), blks.end(i));
+        }
+    }
+
+    /**
+     * @brief Parallelize a loop by automatically splitting it into blocks and submitting each block separately to the queue. Does not return a multi_future, so the user must use wait_for_tasks() or some other method to ensure that the loop finishes executing, otherwise bad things will happen. This overload is used for the special case where the first index is 0.
+     *
+     * @tparam F The type of the function to loop through.
+     * @tparam T The type of the loop indices. Should be a signed or unsigned integer.
+     * @param index_after_last The index after the last index in the loop. The loop will iterate from 0 to (index_after_last - 1) inclusive. In other words, it will be equivalent to "for (T i = 0; i < index_after_last; ++i)". Note that if index_after_last == 0, no blocks will be submitted.
+     * @param loop The function to loop through. Will be called once per block. Should take exactly two arguments: the first index in the block and the index after the last index in the block. loop(start, end) should typically involve a loop of the form "for (T i = start; i < end; ++i)".
+     * @param num_blocks The maximum number of blocks to split the loop into. The default is to use the number of threads in the pool.
+     */
+    template <typename F, typename T>
+    void push_loop(const T index_after_last, F&& loop, const size_t num_blocks = 0)
+    {
+        push_loop(0, index_after_last, std::forward<F>(loop), num_blocks);
+    }
+
+    /**
+     * @brief Push a function with zero or more arguments, but no return value, into the task queue. Does not return a future, so the user must use wait_for_tasks() or some other method to ensure that the task finishes executing, otherwise bad things will happen.
+     *
+     * @tparam F The type of the function.
+     * @tparam A The types of the arguments.
+     * @param task The function to push.
+     * @param args The zero or more arguments to pass to the function. Note that if the task is a class member function, the first argument must be a pointer to the object, i.e. &object (or this), followed by the actual arguments.
+     */
+    template <typename F, typename... A>
+    void push_task(F&& task, A&&... args)
+    {
+        {
+            const std::scoped_lock tasks_lock(tasks_mutex);
+            tasks.push(std::bind(std::forward<F>(task), std::forward<A>(args)...)); // cppcheck-suppress ignoredReturnValue
+        }
+        task_available_cv.notify_one();
+    }
+
+    /**
+     * @brief Reset the number of threads in the pool. Waits for all currently running tasks to be completed, then destroys all threads in the pool and creates a new thread pool with the new number of threads. Any tasks that were waiting in the queue before the pool was reset will then be executed by the new threads. If the pool was paused before resetting it, the new pool will be paused as well.
+     *
+     * @param thread_count_ The number of threads to use. The default value is the total number of hardware threads available, as reported by the implementation. This is usually determined by the number of cores in the CPU. If a core is hyperthreaded, it will count as two threads.
+     */
+    void reset(const concurrency_t thread_count_ = 0)
+    {
+        std::unique_lock tasks_lock(tasks_mutex);
+        const bool was_paused = paused;
+        paused = true;
+        tasks_lock.unlock();
+        wait_for_tasks();
+        destroy_threads();
+        thread_count = determine_thread_count(thread_count_);
+        threads = std::make_unique<std::thread[]>(thread_count);
+        paused = was_paused;
+        create_threads();
+    }
+
+    /**
+     * @brief Submit a function with zero or more arguments into the task queue. If the function has a return value, get a future for the eventual returned value. If the function has no return value, get an std::future<void> which can be used to wait until the task finishes.
+     *
+     * @tparam F The type of the function.
+     * @tparam A The types of the zero or more arguments to pass to the function.
+     * @tparam R The return type of the function (can be void).
+     * @param task The function to submit.
+     * @param args The zero or more arguments to pass to the function. Note that if the task is a class member function, the first argument must be a pointer to the object, i.e. &object (or this), followed by the actual arguments.
+     * @return A future to be used later to wait for the function to finish executing and/or obtain its returned value if it has one.
+     */
+    template <typename F, typename... A, typename R = std::invoke_result_t<std::decay_t<F>, std::decay_t<A>...>>
+    [[nodiscard]] std::future<R> submit(F&& task, A&&... args)
+    {
+        std::shared_ptr<std::promise<R>> task_promise = std::make_shared<std::promise<R>>();
+        push_task(
+            [task_function = std::bind(std::forward<F>(task), std::forward<A>(args)...), task_promise]
+            {
+                try
+                {
+                    if constexpr (std::is_void_v<R>)
+                    {
+                        std::invoke(task_function);
+                        task_promise->set_value();
+                    }
+                    else
+                    {
+                        task_promise->set_value(std::invoke(task_function));
+                    }
+                }
+                catch (...)
+                {
+                    try
+                    {
+                        task_promise->set_exception(std::current_exception());
+                    }
+                    catch (...)
+                    {
+                    }
+                }
+            });
+        return task_promise->get_future();
+    }
+
+    /**
+     * @brief Unpause the pool. The workers will resume retrieving new tasks out of the queue.
+     */
+    void unpause()
+    {
+        const std::scoped_lock tasks_lock(tasks_mutex);
+        paused = false;
+    }
+
+    /**
+     * @brief Wait for tasks to be completed. Normally, this function waits for all tasks, both those that are currently running in the threads and those that are still waiting in the queue. However, if the pool is paused, this function only waits for the currently running tasks (otherwise it would wait forever). Note: To wait for just one specific task, use submit() instead, and call the wait() member function of the generated future.
+     */
+    void wait_for_tasks()
+    {
+        std::unique_lock tasks_lock(tasks_mutex);
+        waiting = true;
+        tasks_done_cv.wait(tasks_lock, [this] { return !tasks_running && (paused || tasks.empty()); });
+        waiting = false;
+    }
+
+    /**
+     * @brief Wait for tasks to be completed, but stop waiting after the specified duration has passed.
+     *
+     * @tparam R An arithmetic type representing the number of ticks to wait.
+     * @tparam P An std::ratio representing the length of each tick in seconds.
+     * @param duration The time duration to wait.
+     * @return true if all tasks finished running, false if the duration expired but some tasks are still running.
+     */
+    template <typename R, typename P>
+    bool wait_for_tasks_duration(const std::chrono::duration<R, P>& duration)
+    {
+        std::unique_lock tasks_lock(tasks_mutex);
+        waiting = true;
+        const bool status = tasks_done_cv.wait_for(tasks_lock, duration, [this] { return !tasks_running && (paused || tasks.empty()); });
+        waiting = false;
+        return status;
+    }
+
+    /**
+     * @brief Wait for tasks to be completed, but stop waiting after the specified time point has been reached.
+     *
+     * @tparam C The type of the clock used to measure time.
+     * @tparam D An std::chrono::duration type used to indicate the time point.
+     * @param timeout_time The time point at which to stop waiting.
+     * @return true if all tasks finished running, false if the time point was reached but some tasks are still running.
+     */
+    template <typename C, typename D>
+    bool wait_for_tasks_until(const std::chrono::time_point<C, D>& timeout_time)
+    {
+        std::unique_lock tasks_lock(tasks_mutex);
+        waiting = true;
+        const bool status = tasks_done_cv.wait_until(tasks_lock, timeout_time, [this] { return !tasks_running && (paused || tasks.empty()); });
+        waiting = false;
+        return status;
+    }
+
+private:
+    // ========================
+    // Private member functions
+    // ========================
+
+    /**
+     * @brief Create the threads in the pool and assign a worker to each thread.
+     */
+    void create_threads()
+    {
+        {
+            const std::scoped_lock tasks_lock(tasks_mutex);
+            workers_running = true;
+        }
+        for (concurrency_t i = 0; i < thread_count; ++i)
+        {
+            threads[i] = std::thread(&thread_pool::worker, this);
+        }
+    }
+
+    /**
+     * @brief Destroy the threads in the pool.
+     */
+    void destroy_threads()
+    {
+        {
+            const std::scoped_lock tasks_lock(tasks_mutex);
+            workers_running = false;
+        }
+        task_available_cv.notify_all();
+        for (concurrency_t i = 0; i < thread_count; ++i)
+        {
+            threads[i].join();
+        }
+    }
+
+    /**
+     * @brief Determine how many threads the pool should have, based on the parameter passed to the constructor or reset().
+     *
+     * @param thread_count_ The parameter passed to the constructor or reset(). If the parameter is a positive number, then the pool will be created with this number of threads. If the parameter is non-positive, or a parameter was not supplied (in which case it will have the default value of 0), then the pool will be created with the total number of hardware threads available, as obtained from std::thread::hardware_concurrency(). If the latter returns a non-positive number for some reason, then the pool will be created with just one thread.
+     * @return The number of threads to use for constructing the pool.
+     */
+    [[nodiscard]] concurrency_t determine_thread_count(const concurrency_t thread_count_) const
+    {
+        if (thread_count_ > 0)
+            return thread_count_;
+        else
+        {
+            if (std::thread::hardware_concurrency() > 0)
+                return std::thread::hardware_concurrency();
+            else
+                return 1;
+        }
+    }
+
+    /**
+     * @brief A worker function to be assigned to each thread in the pool. Waits until it is notified by push_task() that a task is available, and then retrieves the task from the queue and executes it. Once the task finishes, the worker notifies wait_for_tasks() in case it is waiting.
+     */
+    void worker()
+    {
+        std::function<void()> task;
+        while (true)
+        {
+            std::unique_lock tasks_lock(tasks_mutex);
+            task_available_cv.wait(tasks_lock, [this] { return !tasks.empty() || !workers_running; });
+            if (!workers_running)
+                break;
+            if (paused)
+                continue;
+            task = std::move(tasks.front());
+            tasks.pop();
+            ++tasks_running;
+            tasks_lock.unlock();
+            task();
+            tasks_lock.lock();
+            --tasks_running;
+            if (waiting && !tasks_running && (paused || tasks.empty()))
+                tasks_done_cv.notify_all();
+        }
+    }
+
+    // ============
+    // Private data
+    // ============
+
+    /**
+     * @brief A flag indicating whether the workers should pause. When set to true, the workers temporarily stop retrieving new tasks out of the queue, although any tasks already executed will keep running until they are finished. When set to false again, the workers resume retrieving tasks.
+     */
+    bool paused = false;
+
+    /**
+     * @brief A condition variable to notify worker() that a new task has become available.
+     */
+    std::condition_variable task_available_cv = {};
+
+    /**
+     * @brief A condition variable to notify wait_for_tasks() that the tasks are done.
+     */
+    std::condition_variable tasks_done_cv = {};
+
+    /**
+     * @brief A queue of tasks to be executed by the threads.
+     */
+    std::queue<std::function<void()>> tasks = {};
+
+    /**
+     * @brief A counter for the total number of currently running tasks.
+     */
+    size_t tasks_running = 0;
+
+    /**
+     * @brief A mutex to synchronize access to the task queue by different threads.
+     */
+    mutable std::mutex tasks_mutex = {};
+
+    /**
+     * @brief The number of threads in the pool.
+     */
+    concurrency_t thread_count = 0;
+
+    /**
+     * @brief A smart pointer to manage the memory allocated for the threads.
+     */
+    std::unique_ptr<std::thread[]> threads = nullptr;
+
+    /**
+     * @brief A flag indicating that wait_for_tasks() is active and expects to be notified whenever a task is done.
+     */
+    bool waiting = false;
+
+    /**
+     * @brief A flag indicating to the workers to keep running. When set to false, the workers terminate permanently.
+     */
+    bool workers_running = false;
+};
+
+//                                     End class thread_pool                                     //
+// ============================================================================================= //
+
+// ============================================================================================= //
+//                                   Begin class synced_stream                                   //
+
+/**
+ * @brief A helper class to synchronize printing to an output stream by different threads.
+ */
+class [[nodiscard]] synced_stream
+{
+public:
+    /**
+     * @brief Construct a new synced stream.
+     *
+     * @param out_stream_ The output stream to print to. The default value is std::cout.
+     */
+    synced_stream(std::ostream& out_stream_ = std::cout) : out_stream(out_stream_) {}
+
+    /**
+     * @brief Print any number of items into the output stream. Ensures that no other threads print to this stream simultaneously, as long as they all exclusively use the same synced_stream object to print.
+     *
+     * @tparam T The types of the items
+     * @param items The items to print.
+     */
+    template <typename... T>
+    void print(T&&... items)
+    {
+        const std::scoped_lock lock(stream_mutex);
+        (out_stream << ... << std::forward<T>(items));
+    }
+
+    /**
+     * @brief Print any number of items into the output stream, followed by a newline character. Ensures that no other threads print to this stream simultaneously, as long as they all exclusively use the same synced_stream object to print.
+     *
+     * @tparam T The types of the items
+     * @param items The items to print.
+     */
+    template <typename... T>
+    void println(T&&... items)
+    {
+        print(std::forward<T>(items)..., '\n');
+    }
+
+    /**
+     * @brief A stream manipulator to pass to a synced_stream (an explicit cast of std::endl). Prints a newline character to the stream, and then flushes it. Should only be used if flushing is desired, otherwise '\n' should be used instead.
+     */
+    inline static std::ostream& (&endl)(std::ostream&) = static_cast<std::ostream& (&)(std::ostream&)>(std::endl);
+
+    /**
+     * @brief A stream manipulator to pass to a synced_stream (an explicit cast of std::flush). Used to flush the stream.
+     */
+    inline static std::ostream& (&flush)(std::ostream&) = static_cast<std::ostream& (&)(std::ostream&)>(std::flush);
+
+private:
+    /**
+     * @brief The output stream to print to.
+     */
+    std::ostream& out_stream;
+
+    /**
+     * @brief A mutex to synchronize printing.
+     */
+    mutable std::mutex stream_mutex = {};
+};
+
+//                                    End class synced_stream                                    //
+// ============================================================================================= //
+
+// ============================================================================================= //
+//                                       Begin class timer                                       //
+
+/**
+ * @brief A helper class to measure execution time for benchmarking purposes.
+ */
+class [[nodiscard]] timer
+{
+public:
+    /**
+     * @brief Start (or restart) measuring time.
+     */
+    void start()
+    {
+        start_time = std::chrono::steady_clock::now();
+    }
+
+    /**
+     * @brief Stop measuring time and store the elapsed time since start().
+     */
+    void stop()
+    {
+        elapsed_time = std::chrono::steady_clock::now() - start_time;
+    }
+
+    /**
+     * @brief Get the number of milliseconds that have elapsed between start() and stop().
+     *
+     * @return The number of milliseconds.
+     */
+    [[nodiscard]] std::chrono::milliseconds::rep ms() const
+    {
+        return (std::chrono::duration_cast<std::chrono::milliseconds>(elapsed_time)).count();
+    }
+
+private:
+    /**
+     * @brief The time point when measuring started.
+     */
+    std::chrono::time_point<std::chrono::steady_clock> start_time = std::chrono::steady_clock::now();
+
+    /**
+     * @brief The duration that has elapsed between start() and stop().
+     */
+    std::chrono::duration<double> elapsed_time = std::chrono::duration<double>::zero();
+};
+
+//                                        End class timer                                        //
+// ============================================================================================= //
+
+} // namespace BS

include/BS_thread_pool_light.hpp

@@ -0,0 +1,327 @@
+#pragma once
+
+/**
+ * @file BS_thread_pool_light.hpp
+ * @author Barak Shoshany (baraksh@gmail.com) (http://baraksh.com)
+ * @version 3.5.0
+ * @date 2023-05-25
+ * @copyright Copyright (c) 2023 Barak Shoshany. Licensed under the MIT license. If you found this project useful, please consider starring it on GitHub! If you use this library in software of any kind, please provide a link to the GitHub repository https://github.com/bshoshany/thread-pool in the source code and documentation. If you use this library in published research, please cite it as follows: Barak Shoshany, "A C++17 Thread Pool for High-Performance Scientific Computing", doi:10.5281/zenodo.4742687, arXiv:2105.00613 (May 2021)
+ *
+ * @brief BS::thread_pool_light: a fast, lightweight, and easy-to-use C++17 thread pool library. This header file contains a light version of the main library, for use when advanced features are not needed.
+ */
+
+#define BS_THREAD_POOL_LIGHT_VERSION "v3.5.0 (2023-05-25)"
+
+#include <condition_variable> // std::condition_variable
+#include <exception>          // std::current_exception
+#include <functional>         // std::bind, std::function, std::invoke
+#include <future>             // std::future, std::promise
+#include <memory>             // std::make_shared, std::make_unique, std::shared_ptr, std::unique_ptr
+#include <mutex>              // std::mutex, std::scoped_lock, std::unique_lock
+#include <queue>              // std::queue
+#include <thread>             // std::thread
+#include <type_traits>        // std::common_type_t, std::decay_t, std::invoke_result_t, std::is_void_v
+#include <utility>            // std::forward, std::move, std::swap
+
+namespace BS
+{
+/**
+ * @brief A convenient shorthand for the type of std::thread::hardware_concurrency(). Should evaluate to unsigned int.
+ */
+using concurrency_t = std::invoke_result_t<decltype(std::thread::hardware_concurrency)>;
+
+/**
+ * @brief A fast, lightweight, and easy-to-use C++17 thread pool class. This is a lighter version of the main thread pool class.
+ */
+class [[nodiscard]] thread_pool_light
+{
+public:
+    // ============================
+    // Constructors and destructors
+    // ============================
+
+    /**
+     * @brief Construct a new thread pool.
+     *
+     * @param thread_count_ The number of threads to use. The default value is the total number of hardware threads available, as reported by the implementation. This is usually determined by the number of cores in the CPU. If a core is hyperthreaded, it will count as two threads.
+     */
+    thread_pool_light(const concurrency_t thread_count_ = 0) : thread_count(determine_thread_count(thread_count_)), threads(std::make_unique<std::thread[]>(determine_thread_count(thread_count_)))
+    {
+        create_threads();
+    }
+
+    /**
+     * @brief Destruct the thread pool. Waits for all tasks to complete, then destroys all threads.
+     */
+    ~thread_pool_light()
+    {
+        wait_for_tasks();
+        destroy_threads();
+    }
+
+    // =======================
+    // Public member functions
+    // =======================
+
+    /**
+     * @brief Get the number of threads in the pool.
+     *
+     * @return The number of threads.
+     */
+    [[nodiscard]] concurrency_t get_thread_count() const
+    {
+        return thread_count;
+    }
+
+    /**
+     * @brief Parallelize a loop by automatically splitting it into blocks and submitting each block separately to the queue. The user must use wait_for_tasks() or some other method to ensure that the loop finishes executing, otherwise bad things will happen.
+     *
+     * @tparam F The type of the function to loop through.
+     * @tparam T1 The type of the first index in the loop. Should be a signed or unsigned integer.
+     * @tparam T2 The type of the index after the last index in the loop. Should be a signed or unsigned integer. If T1 is not the same as T2, a common type will be automatically inferred.
+     * @tparam T The common type of T1 and T2.
+     * @param first_index The first index in the loop.
+     * @param index_after_last The index after the last index in the loop. The loop will iterate from first_index to (index_after_last - 1) inclusive. In other words, it will be equivalent to "for (T i = first_index; i < index_after_last; ++i)". Note that if index_after_last == first_index, no blocks will be submitted.
+     * @param loop The function to loop through. Will be called once per block. Should take exactly two arguments: the first index in the block and the index after the last index in the block. loop(start, end) should typically involve a loop of the form "for (T i = start; i < end; ++i)".
+     * @param num_blocks The maximum number of blocks to split the loop into. The default is to use the number of threads in the pool.
+     */
+    template <typename F, typename T1, typename T2, typename T = std::common_type_t<T1, T2>>
+    void push_loop(T1 first_index_, T2 index_after_last_, F&& loop, size_t num_blocks = 0)
+    {
+        T first_index = static_cast<T>(first_index_);
+        T index_after_last = static_cast<T>(index_after_last_);
+        if (num_blocks == 0)
+            num_blocks = thread_count;
+        if (index_after_last < first_index)
+            std::swap(index_after_last, first_index);
+        size_t total_size = static_cast<size_t>(index_after_last - first_index);
+        size_t block_size = static_cast<size_t>(total_size / num_blocks);
+        if (block_size == 0)
+        {
+            block_size = 1;
+            num_blocks = (total_size > 1) ? total_size : 1;
+        }
+        if (total_size > 0)
+        {
+            for (size_t i = 0; i < num_blocks; ++i)
+                push_task(std::forward<F>(loop), static_cast<T>(i * block_size) + first_index, (i == num_blocks - 1) ? index_after_last : (static_cast<T>((i + 1) * block_size) + first_index));
+        }
+    }
+
+    /**
+     * @brief Parallelize a loop by automatically splitting it into blocks and submitting each block separately to the queue. The user must use wait_for_tasks() or some other method to ensure that the loop finishes executing, otherwise bad things will happen. This overload is used for the special case where the first index is 0.
+     *
+     * @tparam F The type of the function to loop through.
+     * @tparam T The type of the loop indices. Should be a signed or unsigned integer.
+     * @param index_after_last The index after the last index in the loop. The loop will iterate from 0 to (index_after_last - 1) inclusive. In other words, it will be equivalent to "for (T i = 0; i < index_after_last; ++i)". Note that if index_after_last == 0, no blocks will be submitted.
+     * @param loop The function to loop through. Will be called once per block. Should take exactly two arguments: the first index in the block and the index after the last index in the block. loop(start, end) should typically involve a loop of the form "for (T i = start; i < end; ++i)".
+     * @param num_blocks The maximum number of blocks to split the loop into. The default is to use the number of threads in the pool.
+     */
+    template <typename F, typename T>
+    void push_loop(const T index_after_last, F&& loop, const size_t num_blocks = 0)
+    {
+        push_loop(0, index_after_last, std::forward<F>(loop), num_blocks);
+    }
+
+    /**
+     * @brief Push a function with zero or more arguments, but no return value, into the task queue. Does not return a future, so the user must use wait_for_tasks() or some other method to ensure that the task finishes executing, otherwise bad things will happen.
+     *
+     * @tparam F The type of the function.
+     * @tparam A The types of the arguments.
+     * @param task The function to push.
+     * @param args The zero or more arguments to pass to the function. Note that if the task is a class member function, the first argument must be a pointer to the object, i.e. &object (or this), followed by the actual arguments.
+     */
+    template <typename F, typename... A>
+    void push_task(F&& task, A&&... args)
+    {
+        {
+            const std::scoped_lock tasks_lock(tasks_mutex);
+            tasks.push(std::bind(std::forward<F>(task), std::forward<A>(args)...)); // cppcheck-suppress ignoredReturnValue
+        }
+        task_available_cv.notify_one();
+    }
+
+    /**
+     * @brief Submit a function with zero or more arguments into the task queue. If the function has a return value, get a future for the eventual returned value. If the function has no return value, get an std::future<void> which can be used to wait until the task finishes.
+     *
+     * @tparam F The type of the function.
+     * @tparam A The types of the zero or more arguments to pass to the function.
+     * @tparam R The return type of the function (can be void).
+     * @param task The function to submit.
+     * @param args The zero or more arguments to pass to the function. Note that if the task is a class member function, the first argument must be a pointer to the object, i.e. &object (or this), followed by the actual arguments.
+     * @return A future to be used later to wait for the function to finish executing and/or obtain its returned value if it has one.
+     */
+    template <typename F, typename... A, typename R = std::invoke_result_t<std::decay_t<F>, std::decay_t<A>...>>
+    [[nodiscard]] std::future<R> submit(F&& task, A&&... args)
+    {
+        std::shared_ptr<std::promise<R>> task_promise = std::make_shared<std::promise<R>>();
+        push_task(
+            [task_function = std::bind(std::forward<F>(task), std::forward<A>(args)...), task_promise]
+            {
+                try
+                {
+                    if constexpr (std::is_void_v<R>)
+                    {
+                        std::invoke(task_function);
+                        task_promise->set_value();
+                    }
+                    else
+                    {
+                        task_promise->set_value(std::invoke(task_function));
+                    }
+                }
+                catch (...)
+                {
+                    try
+                    {
+                        task_promise->set_exception(std::current_exception());
+                    }
+                    catch (...)
+                    {
+                    }
+                }
+            });
+        return task_promise->get_future();
+    }
+
+    /**
+     * @brief Wait for tasks to be completed, both those that are currently running in the threads and those that are still waiting in the queue. Note: To wait for just one specific task, use submit() instead, and call the wait() member function of the generated future.
+     */
+    void wait_for_tasks()
+    {
+        std::unique_lock tasks_lock(tasks_mutex);
+        waiting = true;
+        tasks_done_cv.wait(tasks_lock, [this] { return !tasks_running && tasks.empty(); });
+        waiting = false;
+    }
+
+private:
+    // ========================
+    // Private member functions
+    // ========================
+
+    /**
+     * @brief Create the threads in the pool and assign a worker to each thread.
+     */
+    void create_threads()
+    {
+        {
+            const std::scoped_lock tasks_lock(tasks_mutex);
+            workers_running = true;
+        }
+        for (concurrency_t i = 0; i < thread_count; ++i)
+        {
+            threads[i] = std::thread(&thread_pool_light::worker, this);
+        }
+    }
+
+    /**
+     * @brief Destroy the threads in the pool.
+     */
+    void destroy_threads()
+    {
+        {
+            const std::scoped_lock tasks_lock(tasks_mutex);
+            workers_running = false;
+        }
+        task_available_cv.notify_all();
+        for (concurrency_t i = 0; i < thread_count; ++i)
+        {
+            threads[i].join();
+        }
+    }
+
+    /**
+     * @brief Determine how many threads the pool should have, based on the parameter passed to the constructor.
+     *
+     * @param thread_count_ The parameter passed to the constructor. If the parameter is a positive number, then the pool will be created with this number of threads. If the parameter is non-positive, or a parameter was not supplied (in which case it will have the default value of 0), then the pool will be created with the total number of hardware threads available, as obtained from std::thread::hardware_concurrency(). If the latter returns a non-positive number for some reason, then the pool will be created with just one thread.
+     * @return The number of threads to use for constructing the pool.
+     */
+    [[nodiscard]] concurrency_t determine_thread_count(const concurrency_t thread_count_) const
+    {
+        if (thread_count_ > 0)
+            return thread_count_;
+        else
+        {
+            if (std::thread::hardware_concurrency() > 0)
+                return std::thread::hardware_concurrency();
+            else
+                return 1;
+        }
+    }
+
+    /**
+     * @brief A worker function to be assigned to each thread in the pool. Waits until it is notified by push_task() that a task is available, and then retrieves the task from the queue and executes it. Once the task finishes, the worker notifies wait_for_tasks() in case it is waiting.
+     */
+    void worker()
+    {
+        std::function<void()> task;
+        while (true)
+        {
+            std::unique_lock tasks_lock(tasks_mutex);
+            task_available_cv.wait(tasks_lock, [this] { return !tasks.empty() || !workers_running; });
+            if (!workers_running)
+                break;
+            task = std::move(tasks.front());
+            tasks.pop();
+            ++tasks_running;
+            tasks_lock.unlock();
+            task();
+            tasks_lock.lock();
+            --tasks_running;
+            if (waiting && !tasks_running && tasks.empty())
+                tasks_done_cv.notify_all();
+        }
+    }
+
+    // ============
+    // Private data
+    // ============
+
+    /**
+     * @brief A condition variable to notify worker() that a new task has become available.
+     */
+    std::condition_variable task_available_cv = {};
+
+    /**
+     * @brief A condition variable to notify wait_for_tasks() that the tasks are done.
+     */
+    std::condition_variable tasks_done_cv = {};
+
+    /**
+     * @brief A queue of tasks to be executed by the threads.
+     */
+    std::queue<std::function<void()>> tasks = {};
+
+    /**
+     * @brief A counter for the total number of currently running tasks.
+     */
+    size_t tasks_running = 0;
+
+    /**
+     * @brief A mutex to synchronize access to the task queue by different threads.
+     */
+    mutable std::mutex tasks_mutex = {};
+
+    /**
+     * @brief The number of threads in the pool.
+     */
+    concurrency_t thread_count = 0;
+
+    /**
+     * @brief A smart pointer to manage the memory allocated for the threads.
+     */
+    std::unique_ptr<std::thread[]> threads = nullptr;
+
+    /**
+     * @brief A flag indicating that wait_for_tasks() is active and expects to be notified whenever a task is done.
+     */
+    bool waiting = false;
+
+    /**
+     * @brief A flag indicating to the workers to keep running. When set to false, the workers terminate permanently.
+     */
+    bool workers_running = false;
+};
+
+} // namespace BS

tests/BS_thread_pool_test.ps1

@@ -0,0 +1,224 @@
+#!/usr/bin/env pwsh
+$Host.UI.RawUI.WindowTitle = 'BS::thread_pool Test Script'
+
+$TitleColor = 'Green'
+$TextColor = 'Yellow'
+$ErrorColor = 'Red'
+$CommandColor = 'Blue'
+
+Function Write-Title([String] $Title)
+{
+    If ($Title.Length -gt 0)
+    {
+        $Separator = '=' * $Title.Length
+        Write-Host
+        Write-Host $Separator -ForegroundColor $TitleColor
+        Write-Host $Title -ForegroundColor $TitleColor
+        Write-Host $Separator -ForegroundColor $TitleColor
+        Write-Host
+    }
+}
+
+Function Write-Text([String] $Text)
+{
+    Write-Host $Text -ForegroundColor $TextColor
+}
+
+Function Write-Error([String] $Text)
+{
+    Write-Host $Text -ForegroundColor $ErrorColor
+}
+
+Function Write-Command([String] $Text)
+{
+    Write-Host $Text -ForegroundColor $CommandColor
+}
+
+Function Exit-Script([Int] $Code)
+{
+    Set-Location $CurrentDir
+    Exit $Code
+}
+
+$CurrentDir = Get-Location
+
+Write-Title '=== BS::thread_pool test script ==='
+
+$SourceFile = 'BS_thread_pool_test.cpp'
+If (Test-Path -Path $SourceFile)
+{
+    Write-Text "Found source file $SourceFile."
+}
+Else
+{
+    Write-Error "Source file $SourceFile not found, aborting script!"
+    Exit-Script 1
+}
+
+$BuildFolder = Join-Path '..' 'build'
+If (Test-Path -Path $BuildFolder)
+{
+    Write-Text 'Cleaning up build folder...'
+    Remove-Item (Join-Path $BuildFolder '*')
+}
+Else
+{
+    Write-Text 'Creating build folder...'
+    $Null = New-Item $BuildFolder -ItemType 'Directory'
+}
+Write-Text 'Done.'
+
+Write-Title 'Compiling...'
+
+If ($IsWindows)
+{
+    $Extension = '.exe'
+    $PThread = ''
+}
+Else
+{
+    $Extension = ''
+    $PThread = ' -pthread'
+}
+
+$ClangExe = 'BS_thread_pool_test_clang' + $Extension
+$GCCExe = 'BS_thread_pool_test_gcc' + $Extension
+
+$MSVCName = 'BS_thread_pool_test_msvc'
+$MSVCExe = $MSVCName + $Extension
+$MSVCObj = $MSVCName + '.obj'
+
+If (Get-Command 'clang++' -ErrorAction SilentlyContinue)
+{
+    $Clang = $True
+    $FullClangExe = Join-Path $BuildFolder $ClangExe
+    Write-Text 'Compiling with Clang...'
+    $ClangCommand = "clang++ $SourceFile$PThread -std=c++17 -O3 -Wall -Wextra -Wconversion -Wsign-conversion -Wpedantic -Weffc++ -Wshadow -o $FullClangExe"
+    Write-Command $ClangCommand
+    Invoke-Expression $ClangCommand
+    If ($LASTEXITCODE)
+    {
+        Write-Error "Failed to compile, aborting script! (Exit code: $LASTEXITCODE)"
+        Exit-Script $LASTEXITCODE
+    }
+    Else
+    {
+        Write-Text "Successfully compiled to $FullClangExe."
+    }
+}
+Else
+{
+    $Clang = $False
+    Write-Error 'Clang not found, skipping it!'
+}
+
+Write-Host
+
+If (Get-Command 'g++' -ErrorAction SilentlyContinue)
+{
+    $GCC = $True
+    $FullGCCExe = Join-Path $BuildFolder $GCCExe
+    Write-Text 'Compiling with GCC...'
+    $GCCCommand = "g++ $SourceFile$PThread -std=c++17 -O3 -Wall -Wextra -Wconversion -Wsign-conversion -Wpedantic -Weffc++ -Wshadow -o $FullGCCExe"
+    Write-Command $GCCCommand
+    Invoke-Expression $GCCCommand
+    If ($LASTEXITCODE)
+    {
+        Write-Error "Failed to compile, aborting script! (Exit code: $LASTEXITCODE)"
+        Exit-Script $LASTEXITCODE
+    }
+    Else
+    {
+        Write-Text "Successfully compiled to $FullGCCExe."
+    }
+}
+Else
+{
+    $GCC = $False
+    Write-Error 'GCC not found, skipping it!'
+}
+
+Write-Host
+
+If ($IsWindows)
+{
+    $MSVCEnv = 'C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\Launch-VsDevShell.ps1'
+    If (Test-Path $MSVCEnv)
+    {
+        $MSVC = $True
+        $FullMSVCExe = Join-Path $BuildFolder $MSVCExe
+        $FullMSVCObj = Join-Path $BuildFolder $MSVCObj
+        Write-Text 'Compiling with MSVC...'
+        $Env:BS_THREAD_POOL_MSVC_COMMAND = "cl $SourceFile /std:c++17 /permissive- /O2 /W4 /EHsc /Fe:$FullMSVCExe /Fo:$FullMSVCObj"
+        Write-Command $Env:BS_THREAD_POOL_MSVC_COMMAND
+        pwsh -Command {
+            $CurrentDir = Get-Location
+            & 'C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\Launch-VsDevShell.ps1'
+            Set-Location $CurrentDir
+            Invoke-Expression $Env:BS_THREAD_POOL_MSVC_COMMAND
+            Exit $LASTEXITCODE
+        }
+        $Env:BS_THREAD_POOL_MSVC_COMMAND = $Null
+        If ($LASTEXITCODE)
+        {
+            Write-Error "Failed to compile, aborting script! (Exit code: $LASTEXITCODE)"
+            Exit-Script $LASTEXITCODE
+        }
+        Else
+        {
+            Remove-Item $FullMSVCObj
+            Write-Text "Successfully compiled to $FullMSVCExe."
+        }
+    }
+    Else
+    {
+        $MSVC = $False
+        Write-Error 'MSVC not found, skipping it!'
+    }
+}
+Else
+{
+    $MSVC = $False
+}
+
+Write-Title 'Starting tests...'
+
+Set-Location $BuildFolder
+$Repeats = 5;
+
+Write-Text "Each test will be repeated $Repeats times. Outputs can be found in the generated log files."
+
+Function Invoke-Test([String] $Compiler, [String] $Executable)
+{
+    Write-Title "Starting $Compiler tests..."
+    For ($i = 1; $i -Le $Repeats; $i++)
+    {
+        Write-Text "Running $Compiler test #$i of $Repeats..."
+        Invoke-Expression $Executable | Out-Null
+        if ($LASTEXITCODE)
+        {
+            Write-Error "Test Failed, aborting script! (Exit code: $LASTEXITCODE)"
+            Exit-Script $LASTEXITCODE
+        }
+        Write-Text 'Test finished successfully!'
+        Write-Host
+    }
+    Write-Text "$Compiler tests done."
+}
+
+if ($Clang)
+{
+    Invoke-Test 'Clang' (Join-Path '.' $ClangExe)
+}
+if ($GCC)
+{
+    Invoke-Test 'GCC' (Join-Path '.' $GCCExe)
+}
+if ($MSVC)
+{
+    Invoke-Test 'MSVC' (Join-Path '.' $MSVCExe)
+}
+
+Write-Title '=== All tests completed successfully! ==='
+
+Exit-Script 0

thread_pool.hpp

@@ -1,498 +0,0 @@
-#pragma once
-
-/**
- * @file thread_pool.hpp
- * @author Barak Shoshany (baraksh@gmail.com) (http://baraksh.com)
- * @version 1.4
- * @date 2021-05-05
- * @copyright Copyright (c) 2021 Barak Shoshany. Licensed under the MIT license. If you found this code useful, please consider providing a link to the GitHub repository: https://github.com/bshoshany/thread-pool and/or citing the companion paper: https://arxiv.org/abs/2105.00613
- *
- * @brief A C++17 thread pool for high-performance scientific computing.
- * @details A modern C++17-compatible thread pool implementation, built from scratch with high-performance scientific computing in mind. The thread pool is implemented as a single lightweight and self-contained class, and does not have any dependencies other than the C++17 standard library, thus allowing a great degree of portability. In particular, this implementation does not utilize OpenMP or any other high-level multithreading APIs, and thus gives the programmer precise low-level control over the details of the parallelization, which permits more robust optimizations. The thread pool was extensively tested on both AMD and Intel CPUs with up to 40 cores and 80 threads. Other features include automatic generation of futures and easy parallelization of loops. Two helper classes enable synchronizing printing to an output stream by different threads and measuring execution time for benchmarking purposes. Please visit the GitHub repository for documentation and updates, or to submit feature requests and bug reports.
- */
-
-#include <atomic>      // std::atomic
-#include <chrono>      // std::chrono
-#include <cstdint>     // std::int_fast64_t, std::uint_fast32_t
-#include <functional>  // std::function
-#include <future>      // std::future, std::promise
-#include <iostream>    // std::cout, std::ostream
-#include <memory>      // std::shared_ptr, std::unique_ptr
-#include <mutex>       // std::mutex, std::scoped_lock
-#include <queue>       // std::queue
-#include <thread>      // std::this_thread, std::thread
-#include <type_traits> // std::decay_t, std::enable_if_t, std::is_void_v, std::invoke_result_t
-#include <utility>     // std::move, std::swap
-
-// ============================================================================================= //
-//                                    Begin class thread_pool                                    //
-
-/**
- * @brief A C++17 thread pool class. The user submits tasks to be executed into a queue. Whenever a thread becomes available, it pops a task from the queue and executes it. Each task is automatically assigned a future, which can be used to wait for the task to finish executing and/or obtain its eventual return value.
- */
-class thread_pool
-{
-    typedef std::uint_fast32_t ui32;
-
-public:
-    // ============================
-    // Constructors and destructors
-    // ============================
-
-    /**
-     * @brief Construct a new thread pool.
-     *
-     * @param _thread_count The number of threads to use. The default value is the total number of hardware threads available, as reported by the implementation. With a hyperthreaded CPU, this will be twice the number of CPU cores. If the argument is zero, the default value will be used instead.
-     */
-    thread_pool(const ui32 &_thread_count = std::thread::hardware_concurrency())
-        : thread_count(_thread_count ? _thread_count : std::thread::hardware_concurrency()), threads(new std::thread[_thread_count ? _thread_count : std::thread::hardware_concurrency()])
-    {
-        create_threads();
-    }
-
-    /**
-     * @brief Destruct the thread pool. Waits for all tasks to complete, then destroys all threads. Note that if the variable paused is set to true, then any tasks still in the queue will never be executed.
-     */
-    ~thread_pool()
-    {
-        wait_for_tasks();
-        running = false;
-        destroy_threads();
-    }
-
-    // =======================
-    // Public member functions
-    // =======================
-
-    /**
-     * @brief Get the number of tasks currently waiting in the queue to be executed by the threads.
-     *
-     * @return The number of queued tasks.
-     */
-    size_t get_tasks_queued() const
-    {
-        const std::scoped_lock lock(queue_mutex);
-        return tasks.size();
-    }
-
-    /**
-     * @brief Get the number of tasks currently being executed by the threads.
-     *
-     * @return The number of running tasks.
-     */
-    ui32 get_tasks_running() const
-    {
-        return tasks_total - (ui32)get_tasks_queued();
-    }
-
-    /**
-     * @brief Get the total number of unfinished tasks - either still in the queue, or running in a thread.
-     *
-     * @return The total number of tasks.
-     */
-    ui32 get_tasks_total() const
-    {
-        return tasks_total;
-    }
-
-    /**
-     * @brief Get the number of threads in the pool.
-     *
-     * @return The number of threads.
-     */
-    ui32 get_thread_count() const
-    {
-        return thread_count;
-    }
-
-    /**
-     * @brief Parallelize a loop by splitting it into blocks, submitting each block separately to the thread pool, and waiting for all blocks to finish executing. The loop will be equivalent to: for (T i = first_index; i <= last_index; i++) loop(i);
-     *
-     * @tparam T The type of the loop index. Should be a signed or unsigned integer.
-     * @tparam F The type of the function to loop through.
-     * @param first_index The first index in the loop (inclusive).
-     * @param last_index The last index in the loop (inclusive).
-     * @param loop The function to loop through. Should take exactly one argument, the loop index.
-     * @param num_tasks The maximum number of tasks to split the loop into. The default is to use the number of threads in the pool.
-     */
-    template <typename T, typename F>
-    void parallelize_loop(T first_index, T last_index, const F &loop, ui32 num_tasks = 0)
-    {
-        if (num_tasks == 0)
-            num_tasks = thread_count;
-        if (last_index < first_index)
-            std::swap(last_index, first_index);
-        size_t total_size = last_index - first_index + 1;
-        size_t block_size = total_size / num_tasks;
-        if (block_size == 0)
-        {
-            block_size = 1;
-            num_tasks = (ui32)total_size > 1 ? (ui32)total_size : 1;
-        }
-        std::atomic<ui32> blocks_running = 0;
-        for (ui32 t = 0; t < num_tasks; t++)
-        {
-            T start = (T)(t * block_size + first_index);
-            T end = (t == num_tasks - 1) ? last_index : (T)((t + 1) * block_size + first_index - 1);
-            blocks_running++;
-            push_task([start, end, &loop, &blocks_running] {
-                for (T i = start; i <= end; i++)
-                    loop(i);
-                blocks_running--;
-            });
-            while (blocks_running != 0)
-            {
-                sleep_or_yield();
-            }
-        }
-    }
-
-    /**
-     * @brief Push a function with no arguments or return value into the task queue.
-     *
-     * @tparam F The type of the function.
-     * @param task The function to push.
-     */
-    template <typename F>
-    void push_task(const F &task)
-    {
-        tasks_total++;
-        {
-            const std::scoped_lock lock(queue_mutex);
-            tasks.push(std::function<void()>(task));
-        }
-    }
-
-    /**
-     * @brief Push a function with arguments, but no return value, into the task queue.
-     * @details The function is wrapped inside a lambda in order to hide the arguments, as the tasks in the queue must be of type std::function<void()>, so they cannot have any arguments or return value. If no arguments are provided, the other overload will be used, in order to avoid the (slight) overhead of using a lambda.
-     *
-     * @tparam F The type of the function.
-     * @tparam A The types of the arguments.
-     * @param task The function to push.
-     * @param args The arguments to pass to the function.
-     */
-    template <typename F, typename... A>
-    void push_task(const F &task, const A &...args)
-    {
-        push_task([task, args...] { task(args...); });
-    }
-
-    /**
-     * @brief Reset the number of threads in the pool. Waits for all currently running tasks to be completed, then destroys all threads in the pool and creates a new thread pool with the new number of threads. Any tasks that were waiting in the queue before the pool was reset will then be executed by the new threads. If the pool was paused before resetting it, the new pool will be paused as well.
-     *
-     * @param _thread_count The number of threads to use. The default value is the total number of hardware threads available, as reported by the implementation. With a hyperthreaded CPU, this will be twice the number of CPU cores. If the argument is zero, the default value will be used instead.
-     */
-    void reset(const ui32 &_thread_count = std::thread::hardware_concurrency())
-    {
-        bool was_paused = paused;
-        paused = true;
-        wait_for_tasks();
-        running = false;
-        destroy_threads();
-        thread_count = _thread_count ? _thread_count : std::thread::hardware_concurrency();
-        threads.reset(new std::thread[thread_count]);
-        paused = was_paused;
-        create_threads();
-        running = true;
-    }
-
-    /**
-     * @brief Submit a function with zero or more arguments and no return value into the task queue, and get an std::future<bool> that will be set to true upon completion of the task.
-     *
-     * @tparam F The type of the function.
-     * @tparam A The types of the zero or more arguments to pass to the function.
-     * @param task The function to submit.
-     * @param args The zero or more arguments to pass to the function.
-     * @return A future to be used later to check if the function has finished its execution.
-     */
-    template <typename F, typename... A, typename = std::enable_if_t<std::is_void_v<std::invoke_result_t<std::decay_t<F>, std::decay_t<A>...>>>>
-    std::future<bool> submit(const F &task, const A &...args)
-    {
-        std::shared_ptr<std::promise<bool>> promise(new std::promise<bool>);
-        std::future<bool> future = promise->get_future();
-        push_task([task, args..., promise] {
-            task(args...);
-            promise->set_value(true);
-        });
-        return future;
-    }
-
-    /**
-     * @brief Submit a function with zero or more arguments and a return value into the task queue, and get a future for its eventual returned value.
-     *
-     * @tparam F The type of the function.
-     * @tparam A The types of the zero or more arguments to pass to the function.
-     * @tparam R The return type of the function.
-     * @param task The function to submit.
-     * @param args The zero or more arguments to pass to the function.
-     * @return A future to be used later to obtain the function's returned value, waiting for it to finish its execution if needed.
-     */
-    template <typename F, typename... A, typename R = std::invoke_result_t<std::decay_t<F>, std::decay_t<A>...>, typename = std::enable_if_t<!std::is_void_v<R>>>
-    std::future<R> submit(const F &task, const A &...args)
-    {
-        std::shared_ptr<std::promise<R>> promise(new std::promise<R>);
-        std::future<R> future = promise->get_future();
-        push_task([task, args..., promise] { promise->set_value(task(args...)); });
-        return future;
-    }
-
-    /**
-     * @brief Wait for tasks to be completed. Normally, this function waits for all tasks, both those that are currently running in the threads and those that are still waiting in the queue. However, if the variable paused is set to true, this function only waits for the currently running tasks (otherwise it would wait forever). To wait for a specific task, use submit() instead, and call the wait() member function of the generated future.
-     */
-    void wait_for_tasks()
-    {
-        while (true)
-        {
-            if (!paused)
-            {
-                if (tasks_total == 0)
-                    break;
-            }
-            else
-            {
-                if (get_tasks_running() == 0)
-                    break;
-            }
-            sleep_or_yield();
-        }
-    }
-
-    // ===========
-    // Public data
-    // ===========
-
-    /**
-     * @brief An atomic variable indicating to the workers to pause. When set to true, the workers temporarily stop popping new tasks out of the queue, although any tasks already executed will keep running until they are done. Set to false again to resume popping tasks.
-     */
-    std::atomic<bool> paused = false;
-
-    /**
-     * @brief The duration, in microseconds, that the worker function should sleep for when it cannot find any tasks in the queue. If set to 0, then instead of sleeping, the worker function will execute std::this_thread::yield() if there are no tasks in the queue. The default value is 1000.
-     */
-    ui32 sleep_duration = 1000;
-
-private:
-    // ========================
-    // Private member functions
-    // ========================
-
-    /**
-     * @brief Create the threads in the pool and assign a worker to each thread.
-     */
-    void create_threads()
-    {
-        for (ui32 i = 0; i < thread_count; i++)
-        {
-            threads[i] = std::thread(&thread_pool::worker, this);
-        }
-    }
-
-    /**
-     * @brief Destroy the threads in the pool by joining them.
-     */
-    void destroy_threads()
-    {
-        for (ui32 i = 0; i < thread_count; i++)
-        {
-            threads[i].join();
-        }
-    }
-
-    /**
-     * @brief Try to pop a new task out of the queue.
-     *
-     * @param task A reference to the task. Will be populated with a function if the queue is not empty.
-     * @return true if a task was found, false if the queue is empty.
-     */
-    bool pop_task(std::function<void()> &task)
-    {
-        const std::scoped_lock lock(queue_mutex);
-        if (tasks.empty())
-            return false;
-        else
-        {
-            task = std::move(tasks.front());
-            tasks.pop();
-            return true;
-        }
-    }
-
-    /**
-     * @brief Sleep for sleep_duration microseconds. If that variable is set to zero, yield instead.
-     *
-     */
-    void sleep_or_yield()
-    {
-        if (sleep_duration)
-            std::this_thread::sleep_for(std::chrono::microseconds(sleep_duration));
-        else
-            std::this_thread::yield();
-    }
-
-    /**
-     * @brief A worker function to be assigned to each thread in the pool. Continuously pops tasks out of the queue and executes them, as long as the atomic variable running is set to true.
-     */
-    void worker()
-    {
-        while (running)
-        {
-            std::function<void()> task;
-            if (!paused and pop_task(task))
-            {
-                task();
-                tasks_total--;
-            }
-            else
-            {
-                sleep_or_yield();
-            }
-        }
-    }
-
-    // ============
-    // Private data
-    // ============
-
-    /**
-     * @brief A mutex to synchronize access to the task queue by different threads.
-     */
-    mutable std::mutex queue_mutex;
-
-    /**
-     * @brief An atomic variable indicating to the workers to keep running. When set to false, the workers permanently stop working.
-     */
-    std::atomic<bool> running = true;
-
-    /**
-     * @brief A queue of tasks to be executed by the threads.
-     */
-    std::queue<std::function<void()>> tasks;
-
-    /**
-     * @brief The number of threads in the pool.
-     */
-    ui32 thread_count;
-
-    /**
-     * @brief A smart pointer to manage the memory allocated for the threads.
-     */
-    std::unique_ptr<std::thread[]> threads;
-
-    /**
-     * @brief An atomic variable to keep track of the total number of unfinished tasks - either still in the queue, or running in a thread.
-     */
-    std::atomic<ui32> tasks_total = 0;
-};
-
-//                                     End class thread_pool                                     //
-// ============================================================================================= //
-
-// ============================================================================================= //
-//                                   Begin class synced_stream                                   //
-
-/**
- * @brief A helper class to synchronize printing to an output stream by different threads.
- */
-class synced_stream
-{
-public:
-    /**
-     * @brief Construct a new synced stream.
-     *
-     * @param _out_stream The output stream to print to. The default value is std::cout.
-     */
-    synced_stream(std::ostream &_out_stream = std::cout)
-        : out_stream(_out_stream){};
-
-    /**
-     * @brief Print any number of items into the output stream. Ensures that no other threads print to this stream simultaneously, as long as they all exclusively use this synced_stream object to print.
-     *
-     * @tparam T The types of the items
-     * @param items The items to print.
-     */
-    template <typename... T>
-    void print(const T &...items)
-    {
-        const std::scoped_lock lock(stream_mutex);
-        (out_stream << ... << items);
-    }
-
-    /**
-     * @brief Print any number of items into the output stream, followed by a newline character. Ensures that no other threads print to this stream simultaneously, as long as they all exclusively use this synced_stream object to print.
-     *
-     * @tparam T The types of the items
-     * @param items The items to print.
-     */
-    template <typename... T>
-    void println(const T &...items)
-    {
-        print(items..., '\n');
-    }
-
-private:
-    /**
-     * @brief A mutex to synchronize printing.
-     */
-    mutable std::mutex stream_mutex;
-
-    /**
-     * @brief The output stream to print to.
-     */
-    std::ostream &out_stream;
-};
-
-//                                    End class synced_stream                                    //
-// ============================================================================================= //
-
-// ============================================================================================= //
-//                                       Begin class timer                                       //
-
-/**
- * @brief A helper class to measure execution time for benchmarking purposes.
- */
-class timer
-{
-    typedef std::int_fast64_t i64;
-
-public:
-    /**
-     * @brief Start (or restart) measuring time.
-     */
-    void start()
-    {
-        start_time = std::chrono::steady_clock::now();
-    }
-
-    /**
-     * @brief Stop measuring time and store the elapsed time since start().
-     */
-    void stop()
-    {
-        elapsed_time = std::chrono::steady_clock::now() - start_time;
-    }
-
-    /**
-     * @brief Get the number of milliseconds that have elapsed between start() and stop().
-     *
-     * @return The number of milliseconds.
-     */
-    i64 ms() const
-    {
-        return (std::chrono::duration_cast<std::chrono::milliseconds>(elapsed_time)).count();
-    }
-
-private:
-    /**
-     * @brief The time point when measuring started.
-     */
-    std::chrono::time_point<std::chrono::steady_clock> start_time = std::chrono::steady_clock::now();
-
-    /**
-     * @brief The duration that has elapsed between start() and stop().
-     */
-    std::chrono::duration<double> elapsed_time = std::chrono::duration<double>::zero();
-};
-
-//                                        End class timer                                        //
-// ============================================================================================= //