BS::thread_pool

To integrate BS::thread_pool using Conan, add the following to your conanfile.txt:

[requires]
bshoshany-thread-pool/5.1.0

To update, manually change the version number in the [requires] section.

You can enable specific features during compilation by defining the following macros using the -D flag (GCC/Clang) or /D (MSVC):

• BS_THREAD_POOL_TEST_IMPORT_MODULE: Enables importing the library as a C++20 module.
• BS_THREAD_POOL_NATIVE_EXTENSIONS: Enables testing of native extensions.

Note: If using C++20 modules, ensure BS_THREAD_POOL_NATIVE_EXTENSIONS is defined consistently with how the library was compiled.

If C++23 features are available, you can import the C++ Standard Library as a module using import std to achieve faster compilation times. To enable this, you must define the macro BS_THREAD_POOL_IMPORT_STD as a compiler flag at compilation time.

Supported Compiler/Library Combinations:

• Recent LLVM Clang (not Apple Clang) with LLVM libc++.
• Recent GCC with libstdc++.
• Recent MSVC with Microsoft STL.

Important Requirements:

• If BS_THREAD_POOL_IMPORT_STD is defined, you must also import the thread pool library itself as a module. Including the library as a header file while this macro is defined can cause compilation errors in programs that #include standard library headers.
• Do not define the macro in your source code; it must be passed as a compiler flag (e.g., -D BS_THREAD_POOL_IMPORT_STD for Clang/GCC or /D BS_THREAD_POOL_IMPORT_STD for MSVC).

The BS::thread_pool class has optional features disabled by default to minimize overhead. You can enable them by passing a bitmask of BS::tp enumeration flags as a template parameter during instantiation. You can combine multiple flags using the bitwise OR operator |.

Available Flags:

• BS::tp::priority: Enables task priority.
• BS::tp::pause: Enables pausing the pool.
• BS::tp::wait_deadlock_checks: Enables wait deadlock checks.
• BS::tp::none: Disables all optional features (default).

Convenience Aliases:

• BS::light_thread_pool: Equivalent to BS::thread_pool<BS::tp::none>.
• BS::priority_thread_pool: Equivalent to BS::thread_pool<BS::tp::priority>.
• BS::pause_thread_pool: Equivalent to BS::thread_pool<BS::tp::pause>.
• BS::wdc_thread_pool: Equivalent to BS::thread_pool<BS::tp::wait_deadlock_checks>.

To use the library as a module with MSVC, use the Visual Studio Developer PowerShell (ensure the correct architecture, e.g., amd64, is selected via Launch-VsDevShell.ps1).

1. Compile the module:

   cl modules/BS.thread_pool.cppm /c /EHsc /interface /nologo /permissive- /std:c++20 /TP /Zc:__cplusplus /I include /ifcOutput build/BS.thread_pool.ifc /Fo:build/BS.thread_pool.obj

2. Compile your program:

   cl tests/BS_thread_pool_test.cpp build/BS.thread_pool.obj /reference BS.thread_pool=build/BS.thread_pool.ifc /EHsc /nologo /permissive- /std:c++20 /Zc:__cplusplus /Fo:build/BS_thread_pool_test.obj /Fe:build/BS_thread_pool_test.exe /D BS_THREAD_POOL_TEST_IMPORT_MODULE

The repository provides pre-configured .vscode folders to integrate the compile_cpp.py script with Visual Studio Code tasks, debugging, and IntelliSense. Choose the folder corresponding to your operating system and compiler setup:

• .vscode-windows: For Windows using Clang, GCC, or MSVC.
• .vscode-linux: For Linux using Clang or GCC.
• .vscode-macos: For macOS using LLVM Clang (Note: does not support Apple Clang).

These folders contain c_cpp_properties.json, launch.json, and tasks.json files. You may need to modify them to suit your specific local environment.

To use the library as a module with Clang, follow these two steps:

1. Precompile the module:

   clang++ modules/BS.thread_pool.cppm --precompile -std=c++20 -I include -o build/BS.thread_pool.pcm

   Note: Add -D BS_THREAD_POOL_NATIVE_EXTENSIONS to enable native extensions.

2. Compile your program:

   clang++ tests/BS_thread_pool_test.cpp -fmodule-file="BS.thread_pool=build/BS.thread_pool.pcm" -std=c++20 -o build/BS_thread_pool_test -D BS_THREAD_POOL_TEST_IMPORT_MODULE

Important Notes:

• Apple Clang does not support C++20 modules; use the header-only approach instead.
• There is a known bug in Clang with libc++ where std::jthread in a module causes errors. The library automatically falls back to std::thread as a workaround. You can disable this by defining BS_THREAD_POOL_DISABLE_WORKAROUNDS.

The compile_cpp.py script (located in the scripts folder) is a utility for compiling C++ source files across different compilers and platforms. It is particularly useful for testing single-header libraries or working with C++20 modules and C++23 standard library modules.

Note: This script is intended for convenience and is not a replacement for full build systems like CMake. It has been tested with Python v3.14.2.

The scripts/compile_cpp.py script can automatically detect Clang, GCC, and MSVC to compile and run the test program across different C++ standards (17, 20, and 23) and module configurations.

Usage:

python scripts/compile_cpp.py tests/BS_thread_pool_test.cpp --run --try-all --type=release --verbose

The BS_thread_pool_test.cpp file in the tests folder provides a comprehensive test suite and benchmark tool. You can control its behavior using command line arguments.

Command Line Arguments:

• help: Show a help message and exit.
• stdout: Print to the standard output.
• log: Print to a log file (named [executable_name]-yyyy-mm-dd_hh.mm.ss.log).
• tests: Perform standard tests.
• deadlock: Perform long deadlock tests.
• benchmarks: Perform full Mandelbrot set benchmarks.
• plot: Perform quick Mandelbrot set benchmarks (plots the largest image possible in 5 seconds).
• save: Save the Mandelbrot set image to BS_thread_pool_benchmark_mandelbrot.bmp.

Default Behavior: If no arguments are provided, the default is benchmarks log stdout tests. If a default_args.txt file exists in the current or parent directory, it will be used as the default arguments.