BS::thread_pool v3.0.0

v3.0.0 (2022-05-30)

• This is a major new release with many changes and improvements! Please note that code written using previous releases will need to be slightly modified to work with the new release. The changes needed to migrate to the new API are explicitly indicated below for your convenience.
• Breaking changes to the library header file:
  • The header file has been renamed to BS_thread_pool.hpp to avoid potential conflict with other thread pool libraries.
    • API migration: The library must now be included by invoking #include "BS_thread_pool.hpp".
  • All the definitions in the library, including the thread_pool class and the helper classes, are now located in the namespace BS. This namespace will also be used for my other C++ projects, and is intended to ensure consistency between my projects while avoiding potential name conflicts with other libraries.
    • API migration: The thread pool class should now be invoked as BS::thread_pool. Alternatively, it is possible to employ using BS::thread_pool or even using namespace BS and then invoke thread_pool directly. Same for the BS::synced_stream and BS::timer helper classes.
  • The macro THREAD_POOL_VERSION, which contains the version number and release date of the library, has been renamed to BS_THREAD_POOL_VERSION to avoid potential conflicts.
    • API migration: The version must now be read from the macro BS_THREAD_POOL_VERSION.
  • The public member sleep_duration has been removed. The thread pool now uses condition variables instead of sleep to facilitate waiting. This significantly improves performance (by 10%-50% in my testing), drastically decreases idle CPU utilization, and eliminates the need to set an optimal sleep time. This was a highly-requested change; see issue #1, issue #12, and pull request #23.
    • API migration: Remove any code that relates to the public member sleep_duration.
  • The template specializations for submit() have been merged. Now instead of two versions, one for functions with a return value and one for functions without a return value, there is just one version, which can accept any function. This makes the code more compact (and elegant). If a function with no return value is submitted, an std::future<void> is returned (the previous version returned an std::future<bool>)
    • API migration: To wait for a task with no return value, simply call wait() or get() on the corresponding std::future<void>.
  • parallelize_loop() now returns a future in the form of a new BS::multi_future helper class template. The member function wait() of this future allows waiting until all of the loop's blocks finish executing. In previous versions, calling parallelize_loop() both parallelized the loop and waited for the blocks to finish; now it is possible to do other stuff while the loop executes.
    • API migration: Since parallelize_loop() no longer automatically blocks, you should either store the result in a BS::multi_future object and call its wait() member function, or simply call parallelize_loop().wait() to reproduce the old behavior.
• Non-breaking changes to the library header file:
  • It is now possible to use parallelize_loop() with functions that have return values and get these values from all blocks at once through the get() member function of the BS::multi_future.
  • The template specializations for push_task() have been merged. Now instead of two versions, one for functions with arguments and one for functions without arguments, there is just one version, which can accept any function.
  • Constructors have been made explicit. See issue #28.
  • submit() now uses std::make_shared instead of new to create the shared pointer. This means only one memory allocation is performed instead of two, which should improve performance. In addition, all unique pointers are now created using std::make_unique.
  • A new helper class template, BS::multi_future, has been added. It's basically just a wrapper around std::vector<std::future<T>>. This class is used by the new implementation of parallelize_loop() to allow waiting for the entire loop, consisting of multiple tasks with their corresponding futures, to finish executing.
  • BS::multi_future can also be used independently to handle multiple futures at once. For example, you can now keep track of several groups of tasks by storing their futures inside separate BS::multi_future objects and use either wait() to wait for all tasks in a specific group to finish or get() to get an std::vector with the return values of every task in the group.
  • Integer types are now chosen in a smarter way to improve portability, allow for better compatibility with 32-bit systems, and prevent potential conversion errors.
  • Added a new type, BS::concurrency_t, equal to the return type of std::thread::hardware_concurrency(). This is probably pointless, since the C++ standard requires this to be unsigned int, but it seems to me to make the code slightly more portable, in case some non-conforming compiler chooses to use a different integer type.
  • C-style casts have been converted to C++ cast expressions for added clarity.
  • Miscellaneous minor optimizations and style improvements.
• Changes to the test program:
  • The program has been renamed to BS_thread_pool_test.cpp to avoid potential conflict with other thread pool libraries.
  • The program now returns EXIT_FAILURE if any of the tests failed, for automation purposes. See pull request #42.
  • Fixed incorrect check order in check_task_monitoring(). See pull request #43.
  • Added a new test for parallelize_loop() with a return value.
  • Improved some of the tests to make them more reliable. For example, count_unique_threads() now uses futures (stored in a BS::multi_future<void> object).
  • The program now uses std::vector instead of matrices, for both consistency checks and benchmarks, in order to simplify the code and considerably reduce its length.
  • The benchmarks have been simplified. There's now only one test: filling a specific number of vectors of fixed size with random values. This may be replaced with something more practical in a future released, but at least on the systems I've tested on, it does demonstrate a very significant multi-threading speedup.
  • In addition to multi-threaded tests with different numbers of tasks, the benchmark now also includes a single-threaded test. This allows for more accurate benchmarks compared to previous versions, as the (slight) parallelization overhead is now taken into account when calculating the maximum speedup.
  • The program decides how many vectors to use for benchmarking by testing how many are needed to reach a target duration in the single-threaded test. This ensures that the test takes approximately the same amount of time on different systems, and is thus more consistent and portable.
  • Miscellaneous minor optimizations and style improvements.
• Changes to README.md:
  • Many sections have been rewritten and/or polished.
  • Explanations and examples of all the new features have been added.
  • Added an acknowledgements section.
• Miscellaneous changes:
  • Added a CITATION.bib file (in BibTeX format) to the GitHub repository. You can use it to easily cite this package if you use it in any research papers.
  • Added a CITATION.cff file (in YAML format) to the GitHub repository. This should add an option to get a citation in different formats directly from GitHub repository by clicking on "cite this repository" on the sidebar to the right.
  • Added templates for GitHub issues and pull requests.