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/pull_request_template.md

@@ -6,9 +6,15 @@
 
 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 and/or performed any other tests to ensure that it works correctly? If so, please provide information about the test system(s):
+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:

.gitignore

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

BS_thread_pool_light_test.cpp

@@ -1,657 +0,0 @@
-/**
- * @file BS_thread_pool_light_test.cpp
- * @author Barak Shoshany (baraksh@gmail.com) (http://baraksh.com)
- * @version 3.3.0
- * @date 2022-08-03
- * @copyright Copyright (c) 2022 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 program tests all aspects of the light version of the main library, but is not needed in order to use the library.
- */
-
-// Get rid of annoying MSVC warning.
-#ifdef _MSC_VER
-#define _CRT_SECURE_NO_WARNINGS
-#endif
-
-#include <algorithm>          // std::min, std::sort, std::unique
-#include <atomic>             // std::atomic
-#include <chrono>             // std::chrono
-#include <cmath>              // std::abs
-#include <condition_variable> // std::condition_variable
-#include <exception>          // std::exception
-#include <future>             // std::future
-#include <iostream>           // std::cout, std::endl
-#include <memory>             // std::make_unique, std::unique_ptr
-#include <mutex>              // std::mutex, std::scoped_lock, std::unique_lock
-#include <random>             // std::mt19937_64, std::random_device, std::uniform_int_distribution
-#include <stdexcept>          // std::runtime_error
-#include <string>             // std::string, std::to_string
-#include <thread>             // std::this_thread, std::thread
-#include <utility>            // std::forward
-#include <vector>             // std::vector
-
-// Include the header file for the thread pool library.
-#include "BS_thread_pool_light.hpp"
-
-// ================
-// Global variables
-// ================
-
-// A global thread pool object to be used throughout the test.
-BS::thread_pool_light pool;
-
-// A global random_device object to be used to seed some random number generators.
-std::random_device rd;
-
-// Global variables to measure how many checks succeeded and how many failed.
-size_t tests_succeeded = 0;
-size_t tests_failed = 0;
-
-// ================
-// Helper functions
-// ================
-
-/**
- * @brief Print any number of items into both std::cout and the log file, syncing both independently.
- *
- * @tparam T The types of the items.
- * @param items The items to print.
- */
-template <typename... T>
-void print(T&&... items)
-{
-    (std::cout << ... << std::forward<T>(items));
-}
-
-/**
- * @brief Print any number of items into both std::cout and the log file, syncing both independently. Also prints a newline character, and flushes the stream.
- *
- * @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)..., static_cast<std::ostream& (&)(std::ostream&)>(std::endl));
-}
-
-/**
- * @brief Print a stylized header.
- *
- * @param text The text of the header. Will appear between two lines.
- * @param symbol The symbol to use for the lines. Default is '='.
- */
-void print_header(const std::string& text, const char symbol = '=')
-{
-    println();
-    println(std::string(text.length(), symbol));
-    println(text);
-    println(std::string(text.length(), symbol));
-}
-
-/**
- * @brief Check if a condition is met, report the result, and keep count of the total number of successes and failures.
- *
- * @param condition The condition to check.
- */
-void check(const bool condition)
-{
-    if (condition)
-    {
-        println("-> PASSED!");
-        ++tests_succeeded;
-    }
-    else
-    {
-        println("-> FAILED!");
-        ++tests_failed;
-    }
-}
-
-/**
- * @brief Check if the expected result has been obtained, report the result, and keep count of the total number of successes and failures.
- *
- * @param condition The condition to check.
- */
-template <typename T1, typename T2>
-void check(const T1 expected, const T2 obtained)
-{
-    print("Expected: ", expected, ", obtained: ", obtained);
-    if (expected == obtained)
-    {
-        println(" -> PASSED!");
-        ++tests_succeeded;
-    }
-    else
-    {
-        println(" -> FAILED!");
-        ++tests_failed;
-    }
-}
-
-// =========================================
-// Functions to verify the number of threads
-// =========================================
-
-/**
- * @brief Count the number of unique threads in the pool. Submits a number of tasks equal to twice the thread count into the pool. Each task stores the ID of the thread running it, and then waits until released by the main thread. This ensures that each thread in the pool runs at least one task. The number of unique thread IDs is then counted from the stored IDs.
- */
-std::condition_variable ID_cv, total_cv;
-std::mutex ID_mutex, total_mutex;
-BS::concurrency_t count_unique_threads()
-{
-    const BS::concurrency_t num_tasks = pool.get_thread_count() * 2;
-    std::vector<std::thread::id> thread_IDs(num_tasks);
-    std::unique_lock<std::mutex> total_lock(total_mutex);
-    BS::concurrency_t total_count = 0;
-    bool ID_release = false;
-    pool.wait_for_tasks();
-    for (std::thread::id& id : thread_IDs)
-        pool.push_task(
-            [&total_count, &id, &ID_release]
-            {
-                id = std::this_thread::get_id();
-                {
-                    const std::scoped_lock total_lock_local(total_mutex);
-                    ++total_count;
-                }
-                total_cv.notify_one();
-                std::unique_lock<std::mutex> ID_lock_local(ID_mutex);
-                ID_cv.wait(ID_lock_local, [&ID_release] { return ID_release; });
-            });
-    total_cv.wait(total_lock, [&total_count] { return total_count == pool.get_thread_count(); });
-    {
-        const std::scoped_lock ID_lock(ID_mutex);
-        ID_release = true;
-    }
-    ID_cv.notify_all();
-    total_cv.wait(total_lock, [&total_count, &num_tasks] { return total_count == num_tasks; });
-    pool.wait_for_tasks();
-    std::sort(thread_IDs.begin(), thread_IDs.end());
-    return static_cast<BS::concurrency_t>(std::unique(thread_IDs.begin(), thread_IDs.end()) - thread_IDs.begin());
-}
-
-/**
- * @brief Check that the constructor works.
- */
-void check_constructor()
-{
-    println("Checking that the thread pool reports a number of threads equal to the hardware concurrency...");
-    check(std::thread::hardware_concurrency(), pool.get_thread_count());
-    println("Checking that the manually counted number of unique thread IDs is equal to the reported number of threads...");
-    check(pool.get_thread_count(), count_unique_threads());
-}
-
-// =======================================
-// Functions to verify submission of tasks
-// =======================================
-
-/**
- * @brief Check that push_task() works.
- */
-void check_push_task()
-{
-    println("Checking that push_task() works for a function with no arguments or return value...");
-    {
-        bool flag = false;
-        pool.push_task([&flag] { flag = true; });
-        pool.wait_for_tasks();
-        check(flag);
-    }
-    println("Checking that push_task() works for a function with one argument and no return value...");
-    {
-        bool flag = false;
-        pool.push_task([](bool* flag_) { *flag_ = true; }, &flag);
-        pool.wait_for_tasks();
-        check(flag);
-    }
-    println("Checking that push_task() works for a function with two arguments and no return value...");
-    {
-        bool flag1 = false;
-        bool flag2 = false;
-        pool.push_task([](bool* flag1_, bool* flag2_) { *flag1_ = *flag2_ = true; }, &flag1, &flag2);
-        pool.wait_for_tasks();
-        check(flag1 && flag2);
-    }
-}
-
-/**
- * @brief Check that submit() works.
- */
-void check_submit()
-{
-    println("Checking that submit() works for a function with no arguments or return value...");
-    {
-        bool flag = false;
-        pool.submit([&flag] { flag = true; }).wait();
-        check(flag);
-    }
-    println("Checking that submit() works for a function with one argument and no return value...");
-    {
-        bool flag = false;
-        pool.submit([](bool* flag_) { *flag_ = true; }, &flag).wait();
-        check(flag);
-    }
-    println("Checking that submit() works for a function with two arguments and no return value...");
-    {
-        bool flag1 = false;
-        bool flag2 = false;
-        pool.submit([](bool* flag1_, bool* flag2_) { *flag1_ = *flag2_ = true; }, &flag1, &flag2).wait();
-        check(flag1 && flag2);
-    }
-    println("Checking that submit() works for a function with no arguments and a return value...");
-    {
-        bool flag = false;
-        std::future<int> flag_future = pool.submit(
-            [&flag]
-            {
-                flag = true;
-                return 42;
-            });
-        check(flag_future.get() == 42 && flag);
-    }
-    println("Checking that submit() works for a function with one argument and a return value...");
-    {
-        bool flag = false;
-        std::future<int> flag_future = pool.submit(
-            [](bool* flag_)
-            {
-                *flag_ = true;
-                return 42;
-            },
-            &flag);
-        check(flag_future.get() == 42 && flag);
-    }
-    println("Checking that submit() works for a function with two arguments and a return value...");
-    {
-        bool flag1 = false;
-        bool flag2 = false;
-        std::future<int> flag_future = pool.submit(
-            [](bool* flag1_, bool* flag2_)
-            {
-                *flag1_ = *flag2_ = true;
-                return 42;
-            },
-            &flag1, &flag2);
-        check(flag_future.get() == 42 && flag1 && flag2);
-    }
-}
-
-class flag_class
-{
-public:
-    void set_flag_no_args()
-    {
-        flag = true;
-    }
-
-    void set_flag_one_arg(const bool arg)
-    {
-        flag = arg;
-    }
-
-    int set_flag_no_args_return()
-    {
-        flag = true;
-        return 42;
-    }
-
-    int set_flag_one_arg_return(const bool arg)
-    {
-        flag = arg;
-        return 42;
-    }
-
-    bool get_flag() const
-    {
-        return flag;
-    }
-
-    void push_test_flag_no_args()
-    {
-        pool.push_task(&flag_class::set_flag_no_args, this);
-        pool.wait_for_tasks();
-        check(get_flag());
-    }
-
-    void push_test_flag_one_arg()
-    {
-        pool.push_task(&flag_class::set_flag_one_arg, this, true);
-        pool.wait_for_tasks();
-        check(get_flag());
-    }
-
-    void submit_test_flag_no_args()
-    {
-        pool.submit(&flag_class::set_flag_no_args, this).wait();
-        check(get_flag());
-    }
-
-    void submit_test_flag_one_arg()
-    {
-        pool.submit(&flag_class::set_flag_one_arg, this, true).wait();
-        check(get_flag());
-    }
-
-    void submit_test_flag_no_args_return()
-    {
-        std::future<int> flag_future = pool.submit(&flag_class::set_flag_no_args_return, this);
-        check(flag_future.get() == 42 && get_flag());
-    }
-
-    void submit_test_flag_one_arg_return()
-    {
-        std::future<int> flag_future = pool.submit(&flag_class::set_flag_one_arg_return, this, true);
-        check(flag_future.get() == 42 && get_flag());
-    }
-
-private:
-    bool flag = false;
-};
-
-/**
- * @brief Check that submitting member functions works.
- */
-void check_member_function()
-{
-    println("Checking that push_task() works for a member function with no arguments or return value...");
-    {
-        flag_class flag;
-        pool.push_task(&flag_class::set_flag_no_args, &flag);
-        pool.wait_for_tasks();
-        check(flag.get_flag());
-    }
-    println("Checking that push_task() works for a member function with one argument and no return value...");
-    {
-        flag_class flag;
-        pool.push_task(&flag_class::set_flag_one_arg, &flag, true);
-        pool.wait_for_tasks();
-        check(flag.get_flag());
-    }
-    println("Checking that submit() works for a member function with no arguments or return value...");
-    {
-        flag_class flag;
-        pool.submit(&flag_class::set_flag_no_args, &flag).wait();
-        check(flag.get_flag());
-    }
-    println("Checking that submit() works for a member function with one argument and no return value...");
-    {
-        flag_class flag;
-        pool.submit(&flag_class::set_flag_one_arg, &flag, true).wait();
-        check(flag.get_flag());
-    }
-    println("Checking that submit() works for a member function with no arguments and a return value...");
-    {
-        flag_class flag;
-        std::future<int> flag_future = pool.submit(&flag_class::set_flag_no_args_return, &flag);
-        check(flag_future.get() == 42 && flag.get_flag());
-    }
-    println("Checking that submit() works for a member function with one argument and a return value...");
-    {
-        flag_class flag;
-        std::future<int> flag_future = pool.submit(&flag_class::set_flag_one_arg_return, &flag, true);
-        check(flag_future.get() == 42 && flag.get_flag());
-    }
-}
-
-/**
- * @brief Check that submitting member functions within an object works.
- */
-void check_member_function_within_object()
-{
-    println("Checking that push_task() works within an object for a member function with no arguments or return value...");
-    {
-        flag_class flag;
-        flag.push_test_flag_no_args();
-    }
-    println("Checking that push_task() works within an object for a member function with one argument and no return value...");
-    {
-        flag_class flag;
-        flag.push_test_flag_one_arg();
-    }
-    println("Checking that submit() works within an object for a member function with no arguments or return value...");
-    {
-        flag_class flag;
-        flag.submit_test_flag_no_args();
-    }
-    println("Checking that submit() works within an object for a member function with one argument and no return value...");
-    {
-        flag_class flag;
-        flag.submit_test_flag_one_arg();
-    }
-    println("Checking that submit() works within an object for a member function with no arguments and a return value...");
-    {
-        flag_class flag;
-        flag.submit_test_flag_no_args_return();
-    }
-    println("Checking that submit() works within an object for a member function with one argument and a return value...");
-    {
-        flag_class flag;
-        flag.submit_test_flag_one_arg_return();
-    }
-}
-
-/**
- * @brief Check that wait_for_tasks() works.
- */
-void check_wait_for_tasks()
-{
-    const BS::concurrency_t n = pool.get_thread_count() * 10;
-    std::unique_ptr<std::atomic<bool>[]> flags = std::make_unique<std::atomic<bool>[]>(n);
-    for (BS::concurrency_t i = 0; i < n; ++i)
-        pool.push_task(
-            [&flags, i]
-            {
-                std::this_thread::sleep_for(std::chrono::milliseconds(10));
-                flags[i] = true;
-            });
-    println("Waiting for tasks...");
-    pool.wait_for_tasks();
-    bool all_flags = true;
-    for (BS::concurrency_t i = 0; i < n; ++i)
-        all_flags = all_flags && flags[i];
-    check(all_flags);
-}
-
-// ========================================
-// Functions to verify loop parallelization
-// ========================================
-
-/**
- * @brief Check that push_loop() works for a specific range of indices split over a specific number of tasks, with no return value.
- *
- * @param random_start The first index in the loop.
- * @param random_end The last index in the loop plus 1.
- * @param num_tasks The number of tasks.
- */
-template <typename T>
-void check_push_loop_no_return(const int64_t random_start, T random_end, const BS::concurrency_t num_tasks)
-{
-    if (random_start == random_end)
-        ++random_end;
-    println("Verifying that push_loop() from ", random_start, " to ", random_end, " with ", num_tasks, num_tasks == 1 ? " task" : " tasks", " modifies all indices...");
-    const size_t num_indices = static_cast<size_t>(std::abs(random_end - random_start));
-    const int64_t offset = std::min(random_start, static_cast<int64_t>(random_end));
-    std::unique_ptr<std::atomic<bool>[]> flags = std::make_unique<std::atomic<bool>[]>(num_indices);
-    const auto loop = [&flags, offset](const int64_t start, const int64_t end)
-    {
-        for (int64_t i = start; i < end; ++i)
-            flags[static_cast<size_t>(i - offset)] = true;
-    };
-    if (random_start == 0)
-        pool.push_loop(random_end, loop, num_tasks);
-    else
-        pool.push_loop(random_start, random_end, loop, num_tasks);
-    pool.wait_for_tasks();
-    bool all_flags = true;
-    for (size_t i = 0; i < num_indices; ++i)
-        all_flags = all_flags && flags[i];
-    check(all_flags);
-}
-
-/**
- * @brief Check that push_loop() works using several different random values for the range of indices and number of tasks.
- */
-void check_parallelize_loop()
-{
-    std::mt19937_64 mt(rd());
-    std::uniform_int_distribution<int64_t> index_dist(-1000000, 1000000);
-    std::uniform_int_distribution<BS::concurrency_t> task_dist(1, pool.get_thread_count());
-    constexpr uint64_t n = 10;
-    for (uint64_t i = 0; i < n; ++i)
-        check_push_loop_no_return(index_dist(mt), index_dist(mt), task_dist(mt));
-    println("Verifying that push_loop() with identical start and end indices does nothing...");
-    bool flag = true;
-    const int64_t index = index_dist(mt);
-    pool.push_loop(index, index, [&flag](const int64_t, const int64_t) { flag = false; });
-    pool.wait_for_tasks();
-    check(flag);
-    println("Trying push_loop() with start and end indices of different types:");
-    const int64_t start = index_dist(mt);
-    const uint32_t end = static_cast<uint32_t>(std::abs(index_dist(mt)));
-    check_push_loop_no_return(start, end, task_dist(mt));
-    println("Trying the overload for push_loop() for the case where the first index is equal to 0:");
-    check_push_loop_no_return(0, index_dist(mt), task_dist(mt));
-}
-
-// ======================================
-// Functions to verify exception handling
-// ======================================
-
-/**
- * @brief Check that exception handling works.
- */
-void check_exceptions()
-{
-    println("Checking that exceptions are forwarded correctly by submit()...");
-    bool caught = false;
-    auto throws = []
-    {
-        println("Throwing exception...");
-        throw std::runtime_error("Exception thrown!");
-    };
-    std::future<void> my_future = pool.submit(throws);
-    try
-    {
-        my_future.get();
-    }
-    catch (const std::exception& e)
-    {
-        if (e.what() == std::string("Exception thrown!"))
-            caught = true;
-    }
-    check(caught);
-}
-
-// =====================================
-// Functions to verify vector operations
-// =====================================
-
-/**
- * @brief Check that parallelized vector operations work as expected by calculating the sum of two randomized vectors of a specific size in two ways, single-threaded and multithreaded, and comparing the results.
- */
-void check_vector_of_size(const size_t vector_size, const BS::concurrency_t num_tasks)
-{
-    std::vector<int64_t> vector_1(vector_size);
-    std::vector<int64_t> vector_2(vector_size);
-    std::mt19937_64 mt(rd());
-    std::uniform_int_distribution<int64_t> vector_dist(-1000000, 1000000);
-    for (size_t i = 0; i < vector_size; ++i)
-    {
-        vector_1[i] = vector_dist(mt);
-        vector_2[i] = vector_dist(mt);
-    }
-    println("Adding two vectors with ", vector_size, " elements using ", num_tasks, " tasks...");
-    std::vector<int64_t> sum_single(vector_size);
-    for (size_t i = 0; i < vector_size; ++i)
-        sum_single[i] = vector_1[i] + vector_2[i];
-    std::vector<int64_t> sum_multi(vector_size);
-    pool.push_loop(
-        0, vector_size,
-        [&sum_multi, &vector_1, &vector_2](const size_t start, const size_t end)
-        {
-            for (size_t i = start; i < end; ++i)
-                sum_multi[i] = vector_1[i] + vector_2[i];
-        },
-        num_tasks);
-    pool.wait_for_tasks();
-    bool vectors_equal = true;
-    for (size_t i = 0; i < vector_size; ++i)
-        vectors_equal = vectors_equal && (sum_single[i] == sum_multi[i]);
-    check(vectors_equal);
-}
-
-/**
- * @brief Check that parallelized vector operations work as expected by calculating the sum of two randomized vectors in two ways, single-threaded and multithreaded, and comparing the results.
- */
-void check_vectors()
-{
-    std::mt19937_64 mt(rd());
-    std::uniform_int_distribution<size_t> size_dist(0, 1000000);
-    std::uniform_int_distribution<BS::concurrency_t> task_dist(1, pool.get_thread_count());
-    for (size_t i = 0; i < 10; ++i)
-        check_vector_of_size(size_dist(mt), task_dist(mt));
-}
-
-// ==================
-// Main test function
-// ==================
-
-/**
- * @brief Test that various aspects of the library are working as expected.
- */
-void do_tests()
-{
-    print_header("Checking that the constructor works:");
-    check_constructor();
-
-    print_header("Checking that push_task() works:");
-    check_push_task();
-
-    print_header("Checking that submit() works:");
-    check_submit();
-
-    print_header("Checking that submitting member functions works:");
-    check_member_function();
-
-    print_header("Checking that submitting member functions from within an object works:");
-    check_member_function_within_object();
-
-    print_header("Checking that wait_for_tasks() works...");
-    check_wait_for_tasks();
-
-    print_header("Checking that push_loop() works:");
-    check_parallelize_loop();
-
-    print_header("Checking that exception handling works:");
-    check_exceptions();
-
-    print_header("Testing that vector operations produce the expected results:");
-    check_vectors();
-}
-
-int main()
-{
-    println("BS::thread_pool_light: a fast, lightweight, and easy-to-use C++17 thread pool library");
-    println("(c) 2022 Barak Shoshany (baraksh@gmail.com) (http://baraksh.com)");
-    println("GitHub: https://github.com/bshoshany/thread-pool\n");
-
-    println("Thread pool library version is ", BS_THREAD_POOL_VERSION, ".");
-    println("Hardware concurrency is ", std::thread::hardware_concurrency(), ".");
-
-    println("Important: Please do not run any other applications, especially multithreaded applications, in parallel with this test!");
-
-    do_tests();
-
-    if (tests_failed == 0)
-    {
-        print_header("SUCCESS: Passed all " + std::to_string(tests_succeeded) + " checks!", '+');
-        return EXIT_SUCCESS;
-    }
-    else
-    {
-        print_header("FAILURE: Passed " + std::to_string(tests_succeeded) + " checks, but failed " + std::to_string(tests_failed) + "!", '+');
-        println("\nPlease submit a bug report at https://github.com/bshoshany/thread-pool/issues including the exact specifications of your system (OS, CPU, compiler, etc.) and the generated log file.");
-        return EXIT_FAILURE;
-    }
-}

CHANGELOG.md

@@ -1,21 +1,13 @@
-[![DOI:10.5281/zenodo.4742687](https://zenodo.org/badge/DOI/10.5281/zenodo.4742687.svg)](https://doi.org/10.5281/zenodo.4742687)
-[![arXiv:2105.00613](https://img.shields.io/badge/arXiv-2105.00613-b31b1b.svg)](https://arxiv.org/abs/2105.00613)
-[![License: MIT](https://img.shields.io/github/license/bshoshany/thread-pool)](https://github.com/bshoshany/thread-pool/blob/master/LICENSE.txt)
-![Language: C++17](https://img.shields.io/badge/Language-C%2B%2B17-yellow)
-![File size in bytes](https://img.shields.io/github/size/bshoshany/thread-pool/BS_thread_pool.hpp)
-![GitHub last commit](https://img.shields.io/github/last-commit/bshoshany/thread-pool)
-[![GitHub repo stars](https://img.shields.io/github/stars/bshoshany/thread-pool?style=social)](https://github.com/bshoshany/thread-pool)
-[![Twitter @BarakShoshany](https://img.shields.io/twitter/follow/BarakShoshany?style=social)](https://twitter.com/BarakShoshany)
-[![Open in Visual Studio Code](https://img.shields.io/badge/-Open%20in%20Visual%20Studio%20Code-007acc)](https://vscode.dev/github/bshoshany/thread-pool)
-
 # `BS::thread_pool`: a fast, lightweight, and easy-to-use C++17 thread pool library
 
-By Barak Shoshany<br />
-Email: [baraksh@gmail.com](mailto:baraksh@gmail.com)<br />
-Website: [https://baraksh.com/](https://baraksh.com/)<br />
-GitHub: [https://github.com/bshoshany](https://github.com/bshoshany)<br />
+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)
@@ -34,6 +26,58 @@ GitHub: [https://github.com/bshoshany](https://github.com/bshoshany)<br />
 
 ## 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`:

LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Barak Shoshany
+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

README.md

@@ -5,17 +5,16 @@
 ![File size in bytes](https://img.shields.io/github/size/bshoshany/thread-pool/BS_thread_pool.hpp)
 ![GitHub last commit](https://img.shields.io/github/last-commit/bshoshany/thread-pool)
 [![GitHub repo stars](https://img.shields.io/github/stars/bshoshany/thread-pool?style=social)](https://github.com/bshoshany/thread-pool)
-[![Twitter @BarakShoshany](https://img.shields.io/twitter/follow/BarakShoshany?style=social)](https://twitter.com/BarakShoshany)
 [![Open in Visual Studio Code](https://img.shields.io/badge/-Open%20in%20Visual%20Studio%20Code-007acc)](https://vscode.dev/github/bshoshany/thread-pool)
 
 # `BS::thread_pool`: a fast, lightweight, and easy-to-use C++17 thread pool library
 
-By Barak Shoshany<br />
-Email: [baraksh@gmail.com](mailto:baraksh@gmail.com)<br />
-Website: [https://baraksh.com/](https://baraksh.com/)<br />
-GitHub: [https://github.com/bshoshany](https://github.com/bshoshany)<br />
+By Barak Shoshany\
+Email: <baraksh@gmail.com>\
+Website: <https://baraksh.com/>\
+GitHub: <https://github.com/bshoshany>
 
-This is the complete documentation for v3.3.0 of the library, released on 2022-08-03.
+This is the complete documentation for v3.5.0 of the library, released on 2023-05-25.
 
 * [Introduction](#introduction)
     * [Motivation](#motivation)
@@ -32,8 +31,11 @@ This is the complete documentation for v3.3.0 of the library, released on 2022-0
     * [Submitting tasks to the queue with futures](#submitting-tasks-to-the-queue-with-futures)
     * [Submitting tasks to the queue without futures](#submitting-tasks-to-the-queue-without-futures)
     * [Manually waiting for all tasks to complete](#manually-waiting-for-all-tasks-to-complete)
+    * [Waiting with a timeout](#waiting-with-a-timeout)
     * [Submitting class member functions to the queue](#submitting-class-member-functions-to-the-queue)
-    * [Parallelizing loops](#parallelizing-loops)
+    * [Passing task arguments by reference](#passing-task-arguments-by-reference)
+* [Parallelizing loops](#parallelizing-loops)
+    * [Automatic parallelization of loops](#automatic-parallelization-of-loops)
     * [Loops with return values](#loops-with-return-values)
     * [Parallelizing loops without futures](#parallelizing-loops-without-futures)
 * [Helper classes](#helper-classes)
@@ -43,6 +45,7 @@ This is the complete documentation for v3.3.0 of the library, released on 2022-0
 * [Other features](#other-features)
     * [Monitoring the tasks](#monitoring-the-tasks)
     * [Pausing the workers](#pausing-the-workers)
+    * [Purging tasks](#purging-tasks)
     * [Exception handling](#exception-handling)
 * [Testing the package](#testing-the-package)
     * [Automated tests](#automated-tests)
@@ -53,18 +56,19 @@ This is the complete documentation for v3.3.0 of the library, released on 2022-0
     * [Acknowledgements](#acknowledgements)
     * [Starring the repository](#starring-the-repository)
     * [Copyright and citing](#copyright-and-citing)
+    * [Learning more about C++](#learning-more-about-c)
 
 ## Introduction
 
 ### Motivation
 
-Multithreading is essential for modern high-performance computing. Since C++11, the C++ standard library has included built-in low-level multithreading support using constructs such as `std::thread`. However, `std::thread` creates a new thread each time it is called, which can have a significant performance overhead. Furthermore, it is possible to create more threads than the hardware can handle simultaneously, potentially resulting in a substantial slowdown.
+Multithreading is essential for modern high-performance computing. Since C\+\+11, the C++ standard library has included built-in low-level multithreading support using constructs such as `std::thread`. However, `std::thread` creates a new thread each time it is called, which can have a significant performance overhead. Furthermore, it is possible to create more threads than the hardware can handle simultaneously, potentially resulting in a substantial slowdown.
 
-The library presented here contains a thread pool class, `BS::thread_pool`, which avoids these issues by creating a fixed pool of threads once and for all, and then continuously reusing the same threads to perform different tasks throughout the lifetime of the program. By default, the number of threads in the pool is equal to the maximum number of threads that the hardware can run in parallel.
+The library presented here contains a C++ thread pool class, `BS::thread_pool`, which avoids these issues by creating a fixed pool of threads once and for all, and then continuously reusing the same threads to perform different tasks throughout the lifetime of the program. By default, the number of threads in the pool is equal to the maximum number of threads that the hardware can run in parallel.
 
 The user submits tasks to be executed into a queue. Whenever a thread becomes available, it retrieves the next task from the queue and executes it. The pool automatically produces an `std::future` for each task, which allows the user to wait for the task to finish executing and/or obtain its eventual return value, if applicable. Threads and tasks are autonomously managed by the pool in the background, without requiring any input from the user aside from submitting the desired tasks.
 
-The design of this package was guided by four important principles. First, *compactness*: the entire library consists of just one small self-contained header file, with no other components or dependencies. Second, *portability*: the package only utilizes the C++17 standard library, without relying on any compiler extensions or 3rd-party libraries, and is therefore compatible with any modern standards-conforming C++17 compiler on any platform. Third, *ease of use*: the package is extensively documented, and programmers of any level should be able to use it right out of the box.
+The design of this package was guided by four important principles. First, *compactness*: the entire library consists of just one small self-contained header file, with no other components or dependencies. Second, *portability*: the package only utilizes the C\+\+17 standard library, without relying on any compiler extensions or 3rd-party libraries, and is therefore compatible with any modern standards-conforming C\+\+17 compiler on any platform. Third, *ease of use*: the package is extensively documented, and programmers of any level should be able to use it right out of the box.
 
 The fourth and final guiding principle is *performance*: each and every line of code in this library was carefully designed with maximum performance in mind, and performance was tested and verified on a variety of compilers and platforms. Indeed, the library was originally designed for use in the author's own computationally-intensive scientific computing projects, running both on high-end desktop/laptop computers and high-performance computing nodes.
 
@@ -83,44 +87,47 @@ Other, more advanced multithreading libraries may offer more features and/or hig
     * Header-only: no need to install or build the library.
     * Self-contained: no external requirements or dependencies.
     * Portable: uses only the C++ standard library, and works with any C++17-compliant compiler.
-    * Only ~340 lines of code, excluding comments and blank lines.
-    * A stand-alone "light version" of the thread pool is also available in the `BS_thread_pool_light.hpp` header file, with only ~170 lines of code.
+    * Only 247 lines of code, excluding comments, blank lines, and lines containing only a single brace.
+    * A stand-alone "light version" of the C++ thread pool is also available in the `BS_thread_pool_light.hpp` header file, with only 115 lines of code.
 * **Easy to use:**
     * Very simple operation, using a handful of member functions.
     * Every task submitted to the queue using the `submit()` member function automatically generates an `std::future`, which can be used to wait for the task to finish executing and/or obtain its eventual return value.
-    * Optionally, tasks may also be submitted using the `push_task()` member function without generating a future, sacrificing convenience for even greater performance.
+    * Loops can be automatically parallelized into any number of parallel tasks using the `parallelize_loop()` member function, which returns a `BS::multi_future` (see below) that can be used to track the execution of all parallel tasks at once.
+    * If futures are not needed, tasks may be submitted using `push_task()`, and loops can be parallelized using `push_loop()` - sacrificing convenience for even greater performance.
     * The code is thoroughly documented using Doxygen comments - not only the interface, but also the implementation, in case the user would like to make modifications.
     * The included test program `BS_thread_pool_test.cpp` can be used to perform exhaustive automated tests and benchmarks, and also serves as a comprehensive example of how to properly use the package.
 * **Helper classes:**
-    * Automatically parallelize a loop into any number of parallel tasks using the `parallelize_loop()` member function, and track its execution using the `BS::multi_future` helper class.
+    * Track the execution of multiple futures at once using the `BS::multi_future` helper class.
     * Synchronize output to a stream from multiple threads in parallel using the `BS::synced_stream` helper class.
     * Easily measure execution time for benchmarking purposes using the `BS::timer` helper class.
 * **Additional features:**
-    * Easily wait for all tasks in the queue to complete using the `wait_for_tasks()` member function.
+    * Easily wait for all tasks in the queue to complete using the `wait_for_tasks()`, `wait_for_tasks_duration()`, and `wait_for_tasks_until()` member functions.
     * Change the number of threads in the pool safely and on-the-fly as needed using the `reset()` member function.
     * Monitor the number of queued and/or running tasks using the `get_tasks_queued()`, `get_tasks_running()`, and `get_tasks_total()` member functions.
-    * Freely pause and resume the pool using the `pause()`, `unpause()`, and `is_paused()` member functions. When paused, threads do not retrieve new tasks out of the queue.
-    * Catch exceptions thrown by the submitted tasks.
+    * Freely pause and resume the pool using the `pause()`, `unpause()`, and `is_paused()` member functions; when paused, threads do not retrieve new tasks out of the queue.
+    * Purge all tasks currently waiting in the queue with the `purge()` member function.
+    * Catch exceptions thrown by tasks submitted using `submit()` or `parallelize_loop()` from the main thread through their futures.
     * Submit class member functions to the pool, either applied to a specific object or from within the object itself.
+    * Pass arguments to tasks by value, reference, or constant reference.
     * Under continuous and active development. Bug reports and feature requests are welcome, and should be made via [GitHub issues](https://github.com/bshoshany/thread-pool/issues).
 
 ### Compiling and compatibility
 
-This library should successfully compile on any C++17 standard-compliant compiler, on all operating systems and architectures for which such a compiler is available. Compatibility was verified with a 12-core / 24-thread AMD Ryzen 9 3900X CPU using the following compilers and platforms:
+This library should successfully compile on any C++17 standard-compliant compiler, on all operating systems and architectures for which such a compiler is available. Compatibility was verified with a 24-core (8P+16E) / 32-thread Intel i9-13900K CPU using the following compilers and platforms:
 
-* Windows 11 build 22000.795:
-    * [Clang](https://clang.llvm.org/) v14.0.6
-    * [GCC](https://gcc.gnu.org/) v12.1.0 ([WinLibs build](https://winlibs.com/))
-    * [MSVC](https://docs.microsoft.com/en-us/cpp/) v19.32.31332
-* Ubuntu 22.04 LTS:
-    * [Clang](https://clang.llvm.org/) v14.0.0
-    * [GCC](https://gcc.gnu.org/) v12.0.1
+* Windows 11 build 22621.1702:
+    * [Clang](https://clang.llvm.org/) v16.0.4
+    * [GCC](https://gcc.gnu.org/) v13.1.0 ([WinLibs build](https://winlibs.com/))
+    * [MSVC](https://docs.microsoft.com/en-us/cpp/) v19.36.32532
+* Ubuntu 23.04:
+    * [Clang](https://clang.llvm.org/) v16.0.0
+    * [GCC](https://gcc.gnu.org/) v13.0.1
 
-In addition, this library was tested on a [Compute Canada](https://www.computecanada.ca/) node equipped with two 20-core / 40-thread Intel Xeon Gold 6148 CPUs (for a total of 40 cores and 80 threads), running CentOS Linux 7.9.2009, using [GCC](https://gcc.gnu.org/) v12.1.1.
+In addition, this library was tested on a [Digital Research Alliance of Canada](https://alliancecan.ca/en) node equipped with two 20-core / 40-thread Intel Xeon Gold 6148 CPUs (for a total of 40 cores and 80 threads), running CentOS Linux 7.9.2009, using [GCC](https://gcc.gnu.org/) v12.2.0.
 
 The test program `BS_thread_pool_test.cpp` was compiled without warnings (with the warning flags `-Wall -Wextra -Wconversion -Wsign-conversion -Wpedantic -Weffc++ -Wshadow` in GCC/Clang and `/W4` in MSVC), executed, and successfully completed all [automated tests](#testing-the-package) and benchmarks using all of the compilers and systems mentioned above.
 
-As this library requires C++17 features, the code must be compiled with C++17 support:
+As this library requires C\+\+17 features, the code must be compiled with C\+\+17 support:
 
 * For Clang or GCC, use the `-std=c++17` flag. On Linux, you will also need to use the `-pthread` flag to enable the POSIX threads library.
 * For MSVC, use `/std:c++17`, and preferably also `/permissive-` to ensure standards conformance.
@@ -153,7 +160,7 @@ On Windows:
 .\vcpkg install bshoshany-thread-pool:x86-windows bshoshany-thread-pool:x64-windows
 ```
 
-The thread pool will then be available automatically in the build system you integrated vcpkg with (e.g. MSBuild or CMake). Simply write `#include "BS_thread_pool.hpp"` in any project to use the thread pool, without having to copy to file into the project first. I will update the vcpkg port with each new release, so it will be updated automatically when you run `vcpkg upgrade`.
+The C++ thread pool will then be available automatically in the build system you integrated vcpkg with (e.g. MSBuild or CMake). Simply write `#include "BS_thread_pool.hpp"` in any project to use the thread pool, without having to copy to file into the project first. I will update the vcpkg port with each new release, so it will be updated automatically when you run `vcpkg upgrade`.
 
 Please see the [vcpkg repository](https://github.com/microsoft/vcpkg) for more information on how to use vcpkg.
 
@@ -165,7 +172,7 @@ If you are using the [Conan](https://conan.io/) C/C++ package manager, please re
 
 ### Including the library
 
-If you are not using a C++ library manager (such as vcpkg), simply download the [latest release](https://github.com/bshoshany/thread-pool/releases) from the GitHub repository, place the single header file `BS_thread_pool.hpp` in the desired folder, and include it in your program:
+If you are not using a C++ library manager (such as vcpkg), simply download the [latest release](https://github.com/bshoshany/thread-pool/releases) from the GitHub repository, place the single header file `BS_thread_pool.hpp` from the `include` folder of the repository in the desired folder, and include it in your program:
 
 ```cpp
 #include "BS_thread_pool.hpp"
@@ -212,7 +219,7 @@ std::cout << "Thread pool library version is " << BS_THREAD_POOL_VERSION << ".\n
 Sample output:
 
 ```none
-Thread pool library version is v3.1.0 (2022-07-13).
+Thread pool library version is v3.5.0 (2023-05-25).
 ```
 
 This can be used, for example, to allow the same code to work with several incompatible versions of the library.
@@ -335,7 +342,7 @@ pool.push_task(task, arg);
 pool.push_task(task, arg1, arg2);
 ```
 
-**Warning!** Since `push_task()` does not return a future, there is no built-in way for the user to know when the task finishes executing. You must use either `wait_for_tasks()` (see below), or some other method such as condition variables, to ensure that the task finishes executing before trying to use anything that depends on its output. Otherwise, bad things will happen!
+**Warning:** Since `push_task()` does not return a future, there is no built-in way for the user to know when the task finishes executing. You must use either `wait_for_tasks()` (see below), or some other method such as condition variables, to ensure that the task finishes executing before trying to use anything that depends on its output. Otherwise, bad things will happen!
 
 ### Manually waiting for all tasks to complete
 
@@ -371,6 +378,52 @@ after the `for` loop will ensure - as efficiently as possible - that all tasks h
 
 Note, however, that `wait_for_tasks()` will wait for **all** the tasks in the queue, including those that are unrelated to the `for` loop. Using [`parallelize_loop()`](#parallelizing-loops) would make much more sense in this particular case, as it will allow waiting only for the tasks related to the loop.
 
+**Warning:** Never call `wait_for_tasks()` from within a thread of the same thread pool, for example `pool.push_task([] { pool.wait_for_tasks(); })`, as that will cause it to wait forever!
+
+### Waiting with a timeout
+
+Sometimes you may wish to wait for the tasks to complete, but only for a certain amount of time, or until a specific point in time. For example, if the tasks have not yet completed after some time, you may wish to let the user know that there is a delay. This can be achieved using two member functions:
+
+* `wait_for_tasks_duration()` waits for the tasks to be completed, but stops waiting after the specified duration, given as an argument of type `std::chrono::duration`, has passed.
+* `wait_for_tasks_until()` waits for the tasks to be completed, but stops waiting after the specified time point, given as an argument of type `std::chrono::time_point`, has been reached.
+
+Here is an example:
+
+```cpp
+#include "BS_thread_pool.hpp"
+
+int main()
+{
+    BS::thread_pool pool;
+    std::atomic<bool> done = false;
+    pool.push_task(
+        [&done]
+        {
+            std::this_thread::sleep_for(std::chrono::milliseconds(1000));
+            done = true;
+        });
+    while (true)
+    {
+        pool.wait_for_tasks_duration(std::chrono::milliseconds(200));
+        if (!done)
+            std::cout << "Sorry, task is not done yet.\n";
+        else
+            break;
+    }
+    std::cout << "Task done!\n";
+}
+```
+
+The output is:
+
+```none
+Sorry, task is not done yet.
+Sorry, task is not done yet.
+Sorry, task is not done yet.
+Sorry, task is not done yet.
+Task done!
+```
+
 ### Submitting class member functions to the queue
 
 Consider the following program:
@@ -469,7 +522,42 @@ int main()
 }
 ```
 
-### Parallelizing loops
+### Passing task arguments by reference
+
+In C++, it is often crucial to pass function arguments by reference or constant reference, instead of by value. This allows the function to access the object being passed directly, rather than creating a new copy of the object.
+
+When submitting a task using `push_task()` or `submit()`, the task's arguments are always passed by value by default. To pass arguments to the task by reference, you must wrap them with `std::ref()`. Similarly, to pass arguments by constant reference, you must wrap them with `std::cref()`. Here is an example:
+
+```cpp
+#include "BS_thread_pool.hpp"
+
+BS::thread_pool pool;
+
+void increment(int& x)
+{
+    ++x;
+}
+
+void print(const int& x)
+{
+    std::cout << x;
+}
+
+int main()
+{
+    int n = 0;
+    pool.submit(increment, std::ref(n)).wait();
+    pool.submit(print, std::cref(n)).wait();
+}
+```
+
+The `increment()` function takes a **reference** to an integer, and increments that integer. Passing the argument by reference guarantees that `n` itself, in the scope of `main()`, will be incremented - rather than a copy of it in the scope of `increment()`. To pass `n` by reference, we wrapped it inside `std::ref()`. Note that the program will not compile otherwise, since `increment()` only accepts arguments by reference.
+
+Similarly, the `print()` function takes a **constant reference** to an integer, and prints that integer. Passing the argument by constant reference guarantees that the variable will not be accidentally modified by the function, even though we are accessing `n` itself, rather than a copy. To pass `n` by constant reference, we wrapped it inside `std::cref()`.
+
+## Parallelizing loops
+
+### Automatic parallelization of loops
 
 One of the most common and effective methods of parallelization is splitting a loop into smaller loops and running them in parallel. It is most effective in "embarrassingly parallel" computations, such as vector or matrix operations, where each iteration of the loop is completely independent of every other iteration. For example, if we are summing up two vectors of 1000 elements each, and we have 10 threads, we could split the summation into 10 blocks of 100 elements each, and run all the blocks in parallel, potentially increasing performance by up to a factor of 10.
 
@@ -625,7 +713,7 @@ int main()
 
 As with `parallelize_loop()`, the first argument can be omitted if the start index is 0, and the last argument can be omitted if the number of blocks should be equal to the number of threads.
 
-**Warning!** Since `push_loop()` does not return a `BS::multi_future`, there is no built-in way for the user to know when the loop finishes executing. You must use either [`wait_for_tasks()`](#manually-waiting-for-all-tasks-to-complete), or some other method such as condition variables, to ensure that the loop finishes executing before trying to use anything that depends on its output. Otherwise, bad things will happen!
+**Warning:** Since `push_loop()` does not return a `BS::multi_future`, there is no built-in way for the user to know when the loop finishes executing. You must use either [`wait_for_tasks()`](#manually-waiting-for-all-tasks-to-complete), or some other method such as condition variables, to ensure that the loop finishes executing before trying to use anything that depends on its output. Otherwise, bad things will happen!
 
 ## Helper classes
 
@@ -1031,7 +1119,49 @@ All tasks completed.
 
 The first `wait_for_tasks()`, which was called while the pool was not paused, waited for all 8 tasks, both running and queued. The second `wait_for_tasks()`, which was called after pausing the pool, only waited for the 4 running tasks, while the other 8 tasks remained queued, and were not executed since the pool was paused. Finally, the third `wait_for_tasks()`, which was called after unpausing the pool, waited for the remaining 8 tasks, both running and queued.
 
-**Warning**: If the thread pool is destroyed while paused, any tasks still in the queue will never be executed!
+**Warning:** If the thread pool is destroyed while paused, any tasks still in the queue will never be executed!
+
+### Purging tasks
+
+Consider a situation where the user cancels a multi-threaded operation while it is still ongoing. Perhaps the operation was split into multiple tasks, and half of the tasks are currently being executed by the pool's threads, but the other half are still waiting in the queue.
+
+The thread pool cannot terminate the tasks that are already running, as the C++17 standard does not provide that functionality (and in any case, abruptly terminating a task while it's running could have extremely bad consequences, such as memory leaks and data corruption). However, the tasks that are still waiting in the queue can be purged using the `purge()` member function.
+
+Once `purge()` is called, 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; they are gone forever.
+
+Consider for example the following program:
+
+```cpp
+#include "BS_thread_pool.hpp"
+
+BS::synced_stream sync_out;
+BS::thread_pool pool(4);
+
+int main()
+{
+    for (size_t i = 0; i < 8; ++i)
+    {
+        pool.push_task(
+            [i]
+            {
+                std::this_thread::sleep_for(std::chrono::milliseconds(100));
+                sync_out.println("Task ", i, " done.");
+            });
+    }
+    std::this_thread::sleep_for(std::chrono::milliseconds(50));
+    pool.purge();
+    pool.wait_for_tasks();
+}
+```
+
+The program submit 8 tasks to the queue. Each task waits 100 milliseconds and then prints a message. The thread pool has 4 threads, so it will execute the first 4 tasks in parallel, and then the remaining 4. We wait 50 milliseconds, to ensure that the first 4 tasks have all started running. Then we call `purge()` to purge the remaining 4 tasks. As a result, these tasks never get executed. However, since the first 4 tasks are still running when `purge()` is called, they will finish uninterrupted; `purge()` only discards tasks that have not yet started running. The output of the program therefore only contains the messages from the first 4 tasks:
+
+```none
+Task 0 done.
+Task 1 done.
+Task 2 done.
+Task 3 done.
+```
 
 ### Exception handling
 
@@ -1110,334 +1240,55 @@ When using `BS::multi_future` to handle multiple futures at once, exception hand
 
 ## Testing the package
 
-The included file `BS_thread_pool_test.cpp` will perform automated tests of all aspects of the package, and perform simple benchmarks. The output will be printed both to `std::cout` and to a file named `BS_thread_pool_test-yyyy-mm-dd_hh.mm.ss.log` based on the current date and time. In addition, the code is thoroughly documented, and is meant to serve as an extensive example of how to properly use the package.
+### Automated tests
+
+The file `BS_thread_pool_test.cpp` in the `tests` folder of the GitHub repository will perform automated tests of all aspects of the package. The output will be printed both to `std::cout` and to a file named `BS_thread_pool_test-yyyy-mm-dd_hh.mm.ss.log` based on the current date and time. In addition, the code is thoroughly documented, and is meant to serve as an extensive example of how to properly use the package.
 
 Please make sure to:
 
 1. [Compile](#compiling-and-compatibility) `BS_thread_pool_test.cpp` with optimization flags enabled (e.g. `-O3` on GCC / Clang or `/O2` on MSVC).
 2. Run the test without any other applications, especially multithreaded applications, running in parallel.
 
+A PowerShell script, `BS_thread_pool_test.ps1`, is provided for your convenience in the `tests` folder 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.
+
 If any of the tests fail, please [submit a bug report](https://github.com/bshoshany/thread-pool/issues) including the exact specifications of your system (OS, CPU, compiler, etc.) and the generated log file.
 
-### Automated tests
-
-A sample output of a successful run of the automated tests is as follows:
-
-```none
-BS::thread_pool: a fast, lightweight, and easy-to-use C++17 thread pool library
-(c) 2022 Barak Shoshany (baraksh@gmail.com) (http://baraksh.com)
-GitHub: https://github.com/bshoshany/thread-pool
-
-Thread pool library version is v3.3.0 (2022-08-03).
-Hardware concurrency is 24.
-Generating log file: BS_thread_pool_test-2022-08-03_12.32.04.log.
-
-Important: Please do not run any other applications, especially multithreaded applications, in parallel with this test!
-
-====================================
-Checking that the constructor works:
-====================================
-Checking that the thread pool reports a number of threads equal to the hardware concurrency...
-Expected: 24, obtained: 24 -> PASSED!
-Checking that the manually counted number of unique thread IDs is equal to the reported number of threads...
-Expected: 24, obtained: 24 -> PASSED!
-
-============================
-Checking that reset() works:
-============================
-Checking that after reset() the thread pool reports a number of threads equal to half the hardware concurrency...
-Expected: 12, obtained: 12 -> PASSED!
-Checking that after reset() the manually counted number of unique thread IDs is equal to the reported number of threads...
-Expected: 12, obtained: 12 -> PASSED!
-Checking that after a second reset() the thread pool reports a number of threads equal to the hardware concurrency...
-Expected: 24, obtained: 24 -> PASSED!
-Checking that after a second reset() the manually counted number of unique thread IDs is equal to the reported number of threads...
-Expected: 24, obtained: 24 -> PASSED!
-
-================================
-Checking that push_task() works:
-================================
-Checking that push_task() works for a function with no arguments or return value...
--> PASSED!
-Checking that push_task() works for a function with one argument and no return value...
--> PASSED!
-Checking that push_task() works for a function with two arguments and no return value...
--> PASSED!
-
-=============================
-Checking that submit() works:
-=============================
-Checking that submit() works for a function with no arguments or return value...
--> PASSED!
-Checking that submit() works for a function with one argument and no return value...
--> PASSED!
-Checking that submit() works for a function with two arguments and no return value...
--> PASSED!
-Checking that submit() works for a function with no arguments and a return value...
--> PASSED!
-Checking that submit() works for a function with one argument and a return value...
--> PASSED!
-Checking that submit() works for a function with two arguments and a return value...
--> PASSED!
-
-================================================
-Checking that submitting member functions works:
-================================================
-Checking that push_task() works for a member function with no arguments or return value...
--> PASSED!
-Checking that push_task() works for a member function with one argument and no return value...
--> PASSED!
-Checking that submit() works for a member function with no arguments or return value...
--> PASSED!
-Checking that submit() works for a member function with one argument and no return value...
--> PASSED!
-Checking that submit() works for a member function with no arguments and a return value...
--> PASSED!
-Checking that submit() works for a member function with one argument and a return value...
--> PASSED!
-
-======================================================================
-Checking that submitting member functions from within an object works:
-======================================================================
-Checking that push_task() works within an object for a member function with no arguments or return value...
--> PASSED!
-Checking that push_task() works within an object for a member function with one argument and no return value...
--> PASSED!
-Checking that submit() works within an object for a member function with no arguments or return value...
--> PASSED!
-Checking that submit() works within an object for a member function with one argument and no return value...
--> PASSED!
-Checking that submit() works within an object for a member function with no arguments and a return value...
--> PASSED!
-Checking that submit() works within an object for a member function with one argument and a return value...
--> PASSED!
-
-=======================================
-Checking that wait_for_tasks() works...
-=======================================
-Waiting for tasks...
--> PASSED!
-
-======================================================
-Checking that push_loop() and parallelize_loop() work:
-======================================================
-Verifying that push_loop() from 917499 to 884861 with 19 tasks modifies all indices...
--> PASSED!
-Verifying that push_loop() from 235488 to 296304 with 11 tasks modifies all indices...
--> PASSED!
-Verifying that push_loop() from -790296 to -152228 with 21 tasks modifies all indices...
--> PASSED!
-Verifying that push_loop() from -937055 to -135942 with 10 tasks modifies all indices...
--> PASSED!
-Verifying that push_loop() from 372276 to 486867 with 3 tasks modifies all indices...
--> PASSED!
-Verifying that push_loop() from 890415 to -163491 with 5 tasks modifies all indices...
--> PASSED!
-Verifying that push_loop() from 637645 to -894687 with 7 tasks modifies all indices...
--> PASSED!
-Verifying that push_loop() from 308032 to -254915 with 20 tasks modifies all indices...
--> PASSED!
-Verifying that push_loop() from 499518 to 104936 with 17 tasks modifies all indices...
--> PASSED!
-Verifying that push_loop() from 19080 to -378567 with 5 tasks modifies all indices...
--> PASSED!
-Verifying that parallelize_loop() from -298981 to -724834 with 11 tasks modifies all indices...
--> PASSED!
-Verifying that parallelize_loop() from 232695 to 767243 with 3 tasks modifies all indices...
--> PASSED!
-Verifying that parallelize_loop() from 177768 to 966097 with 10 tasks modifies all indices...
--> PASSED!
-Verifying that parallelize_loop() from 474617 to -155690 with 15 tasks modifies all indices...
--> PASSED!
-Verifying that parallelize_loop() from -733576 to 547977 with 9 tasks modifies all indices...
--> PASSED!
-Verifying that parallelize_loop() from -723922 to 992233 with 1 task modifies all indices...
--> PASSED!
-Verifying that parallelize_loop() from 957397 to 364478 with 5 tasks modifies all indices...
--> PASSED!
-Verifying that parallelize_loop() from 776948 to 895847 with 3 tasks modifies all indices...
--> PASSED!
-Verifying that parallelize_loop() from 696779 to 400637 with 17 tasks modifies all indices...
--> PASSED!
-Verifying that parallelize_loop() from -5265 to 746418 with 23 tasks modifies all indices...
--> PASSED!
-Verifying that parallelize_loop() from -229724 to -883103 with 9 tasks correctly sums all indices...
-Expected: -727098445812, obtained: -727098445812 -> PASSED!
-Verifying that parallelize_loop() from 730130 to -370499 with 3 tasks correctly sums all indices...
-Expected: 395819207270, obtained: 395819207270 -> PASSED!
-Verifying that parallelize_loop() from -493633 to 957239 with 14 tasks correctly sums all indices...
-Expected: 672631513560, obtained: 672631513560 -> PASSED!
-Verifying that parallelize_loop() from -455240 to -60850 with 14 tasks correctly sums all indices...
-Expected: -203541129490, obtained: -203541129490 -> PASSED!
-Verifying that parallelize_loop() from -287333 to 298991 with 9 tasks correctly sums all indices...
-Expected: 6834778868, obtained: 6834778868 -> PASSED!
-Verifying that parallelize_loop() from 62326 to -392718 with 18 tasks correctly sums all indices...
-Expected: -150343352292, obtained: -150343352292 -> PASSED!
-Verifying that parallelize_loop() from 663186 to 380865 with 23 tasks correctly sums all indices...
-Expected: 294757240050, obtained: 294757240050 -> PASSED!
-Verifying that parallelize_loop() from 609125 to -43020 with 1 task correctly sums all indices...
-Expected: 369181893080, obtained: 369181893080 -> PASSED!
-Verifying that parallelize_loop() from 465469 to 112037 with 4 tasks correctly sums all indices...
-Expected: 204108747160, obtained: 204108747160 -> PASSED!
-Verifying that parallelize_loop() from 690574 to 113023 with 15 tasks correctly sums all indices...
-Expected: 464117673396, obtained: 464117673396 -> PASSED!
-Verifying that parallelize_loop() with identical start and end indices does nothing...
--> PASSED!
-Trying parallelize_loop() with start and end indices of different types:
-Verifying that parallelize_loop() from 894645 to 908567 with 9 tasks modifies all indices...
--> PASSED!
-Trying the overloads for push_loop() and parallelize_loop() for the case where the first index is equal to 0:
-Verifying that push_loop() from 0 to 949967 with 10 tasks modifies all indices...
--> PASSED!
-Verifying that parallelize_loop() from 0 to 241018 with 3 tasks modifies all indices...
--> PASSED!
-Verifying that parallelize_loop() from 0 to 574984 with 19 tasks correctly sums all indices...
-Expected: 330606025272, obtained: 330606025272 -> PASSED!
-
-====================================
-Checking that task monitoring works:
-====================================
-Resetting pool to 4 threads.
-Submitting 12 tasks.
-After submission, should have: 12 tasks total, 4 tasks running, 8 tasks queued...
-Result: 12 tasks total, 4 tasks running, 8 tasks queued -> PASSED!
-Task 2 released.
-Task 0 released.
-Task 1 released.
-Task 3 released.
-After releasing 4 tasks, should have: 8 tasks total, 4 tasks running, 4 tasks queued...
-Result: 8 tasks total, 4 tasks running, 4 tasks queued -> PASSED!
-Task 4 released.
-Task 7 released.
-Task 6 released.
-Task 5 released.
-After releasing 4 more tasks, should have: 4 tasks total, 4 tasks running, 0 tasks queued...
-Result: 4 tasks total, 4 tasks running, 0 tasks queued -> PASSED!
-Task 11 released.
-Task 10 released.
-Task 9 released.
-Task 8 released.
-After releasing the final 4 tasks, should have: 0 tasks total, 0 tasks running, 0 tasks queued...
-Result: 0 tasks total, 0 tasks running, 0 tasks queued -> PASSED!
-Resetting pool to 24 threads.
-
-============================
-Checking that pausing works:
-============================
-Resetting pool to 4 threads.
-Checking that the pool correctly reports that it is not paused.
--> PASSED!
-Pausing pool.
-Checking that the pool correctly reports that it is paused.
--> PASSED!
-Submitting 12 tasks, each one waiting for 200ms.
-Immediately after submission, should have: 12 tasks total, 0 tasks running, 12 tasks queued...
-Result: 12 tasks total, 0 tasks running, 12 tasks queued -> PASSED!
-300ms later, should still have: 12 tasks total, 0 tasks running, 12 tasks queued...
-Result: 12 tasks total, 0 tasks running, 12 tasks queued -> PASSED!
-Unpausing pool.
-Checking that the pool correctly reports that it is not paused.
--> PASSED!
-Task 1 done.
-Task 2 done.
-Task 0 done.
-Task 3 done.
-300ms later, should have: 8 tasks total, 4 tasks running, 4 tasks queued...
-Result: 8 tasks total, 4 tasks running, 4 tasks queued -> PASSED!
-Pausing pool and using wait_for_tasks() to wait for the running tasks.
-Task 7 done.
-Task 5 done.
-Task 6 done.
-Task 4 done.
-After waiting, should have: 4 tasks total, 0 tasks running, 4 tasks queued...
-Result: 4 tasks total, 0 tasks running, 4 tasks queued -> PASSED!
-200ms later, should still have: 4 tasks total, 0 tasks running, 4 tasks queued...
-Result: 4 tasks total, 0 tasks running, 4 tasks queued -> PASSED!
-Unpausing pool and using wait_for_tasks() to wait for all tasks.
-Task 8 done.
-Task 9 done.
-Task 10 done.
-Task 11 done.
-After waiting, should have: 0 tasks total, 0 tasks running, 0 tasks queued...
-Result: 0 tasks total, 0 tasks running, 0 tasks queued -> PASSED!
-Resetting pool to 24 threads.
-
-=======================================
-Checking that exception handling works:
-=======================================
-Checking that exceptions are forwarded correctly by submit()...
-Throwing exception...
--> PASSED!
-Checking that exceptions are forwarded correctly by BS::multi_future...
-Throwing exception...
-Throwing exception...
--> PASSED!
-
-============================================================
-Testing that vector operations produce the expected results:
-============================================================
-Adding two vectors with 77579 elements using 9 tasks...
--> PASSED!
-Adding two vectors with 925926 elements using 2 tasks...
--> PASSED!
-Adding two vectors with 367682 elements using 22 tasks...
--> PASSED!
-Adding two vectors with 28482 elements using 2 tasks...
--> PASSED!
-Adding two vectors with 486607 elements using 19 tasks...
--> PASSED!
-Adding two vectors with 688249 elements using 10 tasks...
--> PASSED!
-Adding two vectors with 473738 elements using 18 tasks...
--> PASSED!
-Adding two vectors with 743021 elements using 12 tasks...
--> PASSED!
-Adding two vectors with 209804 elements using 11 tasks...
--> PASSED!
-Adding two vectors with 635671 elements using 23 tasks...
--> PASSED!
-
-++++++++++++++++++++++++++++++
-SUCCESS: Passed all 88 checks!
-++++++++++++++++++++++++++++++
-```
-
 ### Performance tests
 
-If all checks passed, `BS_thread_pool_test.cpp` will perform simple benchmarks by filling a specific number of vectors of fixed size with random values. The program decides how many vectors to use 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.
+If all checks passed, `BS_thread_pool_test.cpp` performs simple benchmarks by filling a specific number of vectors of fixed size with values. The program decides how many vectors to use, and of what size, by testing how many are needed to reach a certain target duration in a single-threaded computation. This ensures that the test takes approximately the same amount of time on all systems, and is thus more consistent and portable.
 
-Once the required number of vectors has been determined, the program will test the performance of several multi-threaded tests, dividing the total number of vectors into different numbers of tasks, compare them to the performance of the single-threaded test, and indicate the maximum speedup obtained.
+Once the appropriate number and size of vectors has been determined, the program allocates the vectors and fills them with values, calculated according to a fixed prescription. This operation is performed both single-threaded and multithreaded, with the multithreaded computation spread across multiple tasks submitted to the pool.
 
-Please note that these benchmarks are only intended to demonstrate that the package can provide a significant speedup, and it is highly recommended to perform your own benchmarks with your specific system, compiler, and code.
+Several different multithreaded tests are performed, with the number of tasks either equal to, smaller than, or larger than the pool's thread count. Each test is repeated multiple times, with the run times averaged over all runs of the same test. The run times of the tests are compared, and the maximum speedup obtained is calculated.
 
-Here we will present the results of the performance test running on a high-end desktop computer equipped with a 12-core / 24-thread AMD Ryzen 9 3900X CPU at 3.8 GHz and 32 GB of DDR4 RAM at 3600 MHz, compiled using [MSVC](https://docs.microsoft.com/en-us/cpp/) v19.32.31332 on Windows 11 build 22000.795 with the `/O2` compiler flag. The output was as follows:
+As an example, here are the results of the benchmarks from a [Digital Research Alliance of Canada](https://alliancecan.ca/en) node equipped with two 20-core / 40-thread Intel Xeon Gold 6148 CPUs (for a total of 40 cores and 80 threads), running CentOS Linux 7.9.2009. The tests were compiled using GCC v12.2.0 with the `-O3` and `-march=native` flags. The output was as follows:
 
 ```none
 ======================
 Performing benchmarks:
 ======================
-Using 24 threads.
+Using 80 threads.
 Each test will be repeated 20 times to collect reliable statistics.
-Determining the number and size of vectors to generate in order to achieve an approximate mean execution time of 50 ms with 24 tasks...
-Generating 3312 vectors with 4096 elements each:
-Single-threaded, mean execution time was  542.2 ms with standard deviation  5.8 ms.
-With    6 tasks, mean execution time was   95.2 ms with standard deviation  1.7 ms.
-With   12 tasks, mean execution time was   49.6 ms with standard deviation  0.7 ms.
-With   24 tasks, mean execution time was   29.0 ms with standard deviation  2.9 ms.
-With   48 tasks, mean execution time was   33.2 ms with standard deviation  4.3 ms.
-With   96 tasks, mean execution time was   35.5 ms with standard deviation  1.9 ms.
-Maximum speedup obtained by multithreading vs. single-threading: 18.7x, using 24 tasks.
+Determining the number and size of vectors to generate in order to achieve an approximate mean execution time of 50 ms with 80 tasks...
+Generating 3840 vectors with 5120 elements each:
+Single-threaded, mean execution time was 2122.5 ms with standard deviation 18.1 ms.
+With   20 tasks, mean execution time was  119.8 ms with standard deviation 13.3 ms.
+With   40 tasks, mean execution time was   68.9 ms with standard deviation  0.3 ms.
+With   80 tasks, mean execution time was   45.5 ms with standard deviation  6.2 ms.
+With  160 tasks, mean execution time was   39.3 ms with standard deviation  3.3 ms.
+With  320 tasks, mean execution time was   40.4 ms with standard deviation  2.4 ms.
+Maximum speedup obtained by multithreading vs. single-threading: 53.9x, using 160 tasks.
 
 +++++++++++++++++++++++++++++++++++++++
 Thread pool performance test completed!
 +++++++++++++++++++++++++++++++++++++++
 ```
 
-This CPU has 12 physical cores, with each core providing two separate logical cores via hyperthreading, for a total of 24 threads. Without hyperthreading, we would expect a maximum theoretical speedup of 12x. With hyperthreading, one might naively expect to achieve up to a 24x speedup, but this is in fact impossible, as both logical cores share the same physical core's resources. However, generally we would expect [an estimated 30% additional speedup](https://software.intel.com/content/www/us/en/develop/articles/how-to-determine-the-effectiveness-of-hyper-threading-technology-with-an-application.html) from hyperthreading, which amounts to around 15.6x in this case. In our performance test, we see a speedup of 18.7x, saturating and even surpassing this estimated theoretical upper bound.
+These two CPUs have 40 physical cores in total, with each core providing two separate logical cores via hyperthreading, for a total of 80 threads. Without hyperthreading, we would expect a maximum theoretical speedup of 40x. With hyperthreading, one might naively expect to achieve up to an 80x speedup, but this is in fact impossible, as each pair of hyperthreaded logical cores share the same physical core's resources. However, generally we would expect at most an estimated 30% additional speedup from hyperthreading, which amounts to around 52x in this case. The speedup of 53.9x in our performance test exceeds this estimate.
 
 ## The light version of the package
 
-This package started out as a very lightweight thread pool, but over time has expanded to include many additional features and 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`, which is about half the size of the full package.
+This package started out as a very lightweight C++ thread pool, but over time has expanded to include many additional features and 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`.
 
 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:
 
@@ -1447,9 +1298,9 @@ This file does not contain any of the helper classes, only a new `BS::thread_poo
 * `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.
+Note that 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. However, if you wish to use both the light and non-light thread pool classes in the same project, you can include both header files.
 
-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.
+The test program `BS_thread_pool_test.cpp` tests both the full and the light versions of the package. If needed, the current version of the light thread pool can be obtained using the macro `BS_THREAD_POOL_LIGHT_VERSION`.
 
 ## About the project
 
@@ -1469,9 +1320,9 @@ If you found this project useful, please consider [starring it on GitHub](https:
 
 ### Copyright and citing
 
-Copyright (c) 2022 [Barak Shoshany](http://baraksh.com). Licensed under the [MIT license](LICENSE.txt).
+Copyright (c) 2023 [Barak Shoshany](http://baraksh.com). Licensed under the [MIT license](LICENSE.txt).
 
-If you use the 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 C++ thread pool 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:
 
@@ -1496,3 +1347,7 @@ You can use the following BibTeX entry:
 ```
 
 Please note that the [companion paper on arXiv](https://arxiv.org/abs/2105.00613) is updated infrequently. The paper is intended to facilitate discovery of the package by scientists who may find it useful for scientific computing purposes and to allow citing the package in scientific research, but most users should read the `README.md` file on [the GitHub repository](https://github.com/bshoshany/thread-pool) instead, as it is guaranteed to always be up to date.
+
+### Learning more about C++
+
+Beginner C++ programmers may be interested in [my lecture notes](https://baraksh.com/CSE701/notes.php) for a course taught at McMaster University, which teach modern C and C++ from scratch, including some of the advanced techniques and programming practices used in developing this library.

include/BS_thread_pool.hpp

@@ -3,16 +3,15 @@
 /**
  * @file BS_thread_pool.hpp
  * @author Barak Shoshany (baraksh@gmail.com) (http://baraksh.com)
- * @version 3.3.0
- * @date 2022-08-03
- * @copyright Copyright (c) 2022 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)
+ * @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.3.0 (2022-08-03)"
+#define BS_THREAD_POOL_VERSION "v3.5.0 (2023-05-25)"
 
-#include <atomic>             // std::atomic
 #include <chrono>             // std::chrono
 #include <condition_variable> // std::condition_variable
 #include <exception>          // std::current_exception
@@ -286,17 +285,18 @@ public:
     [[nodiscard]] size_t get_tasks_running() const
     {
         const std::scoped_lock tasks_lock(tasks_mutex);
-        return tasks_total - tasks.size();
+        return tasks_running;
     }
 
     /**
-     * @brief Get the total number of unfinished tasks: either still in the queue, or running in a thread. Note that get_tasks_total() == get_tasks_queued() + get_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
     {
-        return tasks_total;
+        const std::scoped_lock tasks_lock(tasks_mutex);
+        return tasks_running + tasks.size();
     }
 
     /**
@@ -316,6 +316,7 @@ public:
      */
     [[nodiscard]] bool is_paused() const
     {
+        const std::scoped_lock tasks_lock(tasks_mutex);
         return paused;
     }
 
@@ -372,9 +373,20 @@ public:
      */
     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.
      *
@@ -424,12 +436,10 @@ public:
     template <typename F, typename... A>
     void push_task(F&& task, A&&... args)
     {
-        std::function<void()> task_function = std::bind(std::forward<F>(task), std::forward<A>(args)...);
         {
             const std::scoped_lock tasks_lock(tasks_mutex);
-            tasks.push(task_function);
+            tasks.push(std::bind(std::forward<F>(task), std::forward<A>(args)...)); // cppcheck-suppress ignoredReturnValue
         }
-        ++tasks_total;
         task_available_cv.notify_one();
     }
 
@@ -440,8 +450,10 @@ public:
      */
     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_);
@@ -463,10 +475,9 @@ public:
     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::function<R()> task_function = std::bind(std::forward<F>(task), std::forward<A>(args)...);
         std::shared_ptr<std::promise<R>> task_promise = std::make_shared<std::promise<R>>();
         push_task(
-            [task_function, task_promise]
+            [task_function = std::bind(std::forward<F>(task), std::forward<A>(args)...), task_promise]
             {
                 try
                 {
@@ -499,6 +510,7 @@ public:
      */
     void unpause()
     {
+        const std::scoped_lock tasks_lock(tasks_mutex);
         paused = false;
     }
 
@@ -507,12 +519,48 @@ public:
      */
     void wait_for_tasks()
     {
+        std::unique_lock tasks_lock(tasks_mutex);
         waiting = true;
-        std::unique_lock<std::mutex> tasks_lock(tasks_mutex);
-        task_done_cv.wait(tasks_lock, [this] { return (tasks_total == (paused ? tasks.size() : 0)); });
+        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
@@ -523,7 +571,10 @@ private:
      */
     void create_threads()
     {
-        running = true;
+        {
+            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);
@@ -535,7 +586,10 @@ private:
      */
     void destroy_threads()
     {
-        running = false;
+        {
+            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)
         {
@@ -549,7 +603,7 @@ private:
      * @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_)
+    [[nodiscard]] concurrency_t determine_thread_count(const concurrency_t thread_count_) const
     {
         if (thread_count_ > 0)
             return thread_count_;
@@ -567,22 +621,24 @@ private:
      */
     void worker()
     {
-        while (running)
+        std::function<void()> task;
+        while (true)
         {
-            std::function<void()> task;
-            std::unique_lock<std::mutex> tasks_lock(tasks_mutex);
-            task_available_cv.wait(tasks_lock, [this] { return !tasks.empty() || !running; });
-            if (running && !paused)
-            {
-                task = std::move(tasks.front());
-                tasks.pop();
-                tasks_lock.unlock();
-                task();
-                tasks_lock.lock();
-                --tasks_total;
-                if (waiting)
-                    task_done_cv.notify_one();
-            }
+            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();
         }
     }
 
@@ -591,24 +647,19 @@ private:
     // ============
 
     /**
-     * @brief An atomic variable 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.
+     * @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.
      */
-    std::atomic<bool> paused = false;
+    bool paused = false;
 
     /**
-     * @brief An atomic variable indicating to the workers to keep running. When set to false, the workers permanently stop working.
-     */
-    std::atomic<bool> running = false;
-
-    /**
-     * @brief A condition variable used to notify worker() that a new task has become available.
+     * @brief A condition variable to notify worker() that a new task has become available.
      */
     std::condition_variable task_available_cv = {};
 
     /**
-     * @brief A condition variable used to notify wait_for_tasks() that a tasks is done.
+     * @brief A condition variable to notify wait_for_tasks() that the tasks are done.
      */
-    std::condition_variable task_done_cv = {};
+    std::condition_variable tasks_done_cv = {};
 
     /**
      * @brief A queue of tasks to be executed by the threads.
@@ -616,9 +667,9 @@ private:
     std::queue<std::function<void()>> tasks = {};
 
     /**
-     * @brief An atomic variable to keep track of the total number of unfinished tasks - either still in the queue, or running in a thread.
+     * @brief A counter for the total number of currently running tasks.
      */
-    std::atomic<size_t> tasks_total = 0;
+    size_t tasks_running = 0;
 
     /**
      * @brief A mutex to synchronize access to the task queue by different threads.
@@ -636,9 +687,14 @@ private:
     std::unique_ptr<std::thread[]> threads = nullptr;
 
     /**
-     * @brief An atomic variable indicating that wait_for_tasks() is active and expects to be notified whenever a task is done.
+     * @brief A flag indicating that wait_for_tasks() is active and expects to be notified whenever a task is done.
      */
-    std::atomic<bool> waiting = false;
+    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                                     //

include/BS_thread_pool_light.hpp

@@ -3,16 +3,15 @@
 /**
  * @file BS_thread_pool_light.hpp
  * @author Barak Shoshany (baraksh@gmail.com) (http://baraksh.com)
- * @version 3.3.0
- * @date 2022-08-03
- * @copyright Copyright (c) 2022 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)
+ * @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_VERSION "v3.3.0 (2022-08-03) [light]"
+#define BS_THREAD_POOL_LIGHT_VERSION "v3.5.0 (2023-05-25)"
 
-#include <atomic>             // std::atomic
 #include <condition_variable> // std::condition_variable
 #include <exception>          // std::current_exception
 #include <functional>         // std::bind, std::function, std::invoke
@@ -135,12 +134,10 @@ public:
     template <typename F, typename... A>
     void push_task(F&& task, A&&... args)
     {
-        std::function<void()> task_function = std::bind(std::forward<F>(task), std::forward<A>(args)...);
         {
             const std::scoped_lock tasks_lock(tasks_mutex);
-            tasks.push(task_function);
+            tasks.push(std::bind(std::forward<F>(task), std::forward<A>(args)...)); // cppcheck-suppress ignoredReturnValue
         }
-        ++tasks_total;
         task_available_cv.notify_one();
     }
 
@@ -157,10 +154,9 @@ public:
     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::function<R()> task_function = std::bind(std::forward<F>(task), std::forward<A>(args)...);
         std::shared_ptr<std::promise<R>> task_promise = std::make_shared<std::promise<R>>();
         push_task(
-            [task_function, task_promise]
+            [task_function = std::bind(std::forward<F>(task), std::forward<A>(args)...), task_promise]
             {
                 try
                 {
@@ -189,13 +185,13 @@ public:
     }
 
     /**
-     * @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. Note: To wait for just one specific task, use submit() instead, and call the wait() member function of the generated 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;
-        std::unique_lock<std::mutex> tasks_lock(tasks_mutex);
-        task_done_cv.wait(tasks_lock, [this] { return (tasks_total == 0); });
+        tasks_done_cv.wait(tasks_lock, [this] { return !tasks_running && tasks.empty(); });
         waiting = false;
     }
 
@@ -209,7 +205,10 @@ private:
      */
     void create_threads()
     {
-        running = true;
+        {
+            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);
@@ -221,7 +220,10 @@ private:
      */
     void destroy_threads()
     {
-        running = false;
+        {
+            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)
         {
@@ -235,7 +237,7 @@ private:
      * @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_)
+    [[nodiscard]] concurrency_t determine_thread_count(const concurrency_t thread_count_) const
     {
         if (thread_count_ > 0)
             return thread_count_;
@@ -253,22 +255,22 @@ private:
      */
     void worker()
     {
-        while (running)
+        std::function<void()> task;
+        while (true)
         {
-            std::function<void()> task;
-            std::unique_lock<std::mutex> tasks_lock(tasks_mutex);
-            task_available_cv.wait(tasks_lock, [this] { return !tasks.empty() || !running; });
-            if (running)
-            {
-                task = std::move(tasks.front());
-                tasks.pop();
-                tasks_lock.unlock();
-                task();
-                tasks_lock.lock();
-                --tasks_total;
-                if (waiting)
-                    task_done_cv.notify_one();
-            }
+            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();
         }
     }
 
@@ -277,19 +279,14 @@ private:
     // ============
 
     /**
-     * @brief An atomic variable indicating to the workers to keep running. When set to false, the workers permanently stop working.
-     */
-    std::atomic<bool> running = false;
-
-    /**
-     * @brief A condition variable used to notify worker() that a new task has become available.
+     * @brief A condition variable to notify worker() that a new task has become available.
      */
     std::condition_variable task_available_cv = {};
 
     /**
-     * @brief A condition variable used to notify wait_for_tasks() that a tasks is done.
+     * @brief A condition variable to notify wait_for_tasks() that the tasks are done.
      */
-    std::condition_variable task_done_cv = {};
+    std::condition_variable tasks_done_cv = {};
 
     /**
      * @brief A queue of tasks to be executed by the threads.
@@ -297,9 +294,9 @@ private:
     std::queue<std::function<void()>> tasks = {};
 
     /**
-     * @brief An atomic variable to keep track of the total number of unfinished tasks - either still in the queue, or running in a thread.
+     * @brief A counter for the total number of currently running tasks.
      */
-    std::atomic<size_t> tasks_total = 0;
+    size_t tasks_running = 0;
 
     /**
      * @brief A mutex to synchronize access to the task queue by different threads.
@@ -317,9 +314,14 @@ private:
     std::unique_ptr<std::thread[]> threads = nullptr;
 
     /**
-     * @brief An atomic variable indicating that wait_for_tasks() is active and expects to be notified whenever a task is done.
+     * @brief A flag indicating that wait_for_tasks() is active and expects to be notified whenever a task is done.
      */
-    std::atomic<bool> waiting = false;
+    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