beman.timed_lock_alg : Timed lock algorithms for multiple lockables

beman.timed_lock_alg implements timed lock algorithms for multiple lockables.

Implements: std::try_lock_until and std::try_lock_for proposed in Timed lock algorithms for multiple lockables (P3832R0).

Status: Under development and not yet ready for production use.

License

beman.timed_lock_alg is licensed under the MIT License.

Usage

std::try_lock_until and std::try_lock_for are a function templates usable with zero to many TimedLockables.

Example:

std::timed_mutex m1, m2;
if (std::try_lock_for(100ms, m1, m2) == -1) {
    // success
    std::scoped_lock sl(std::adopt_lock, m1, m2);
    // ...
} else {
    // failed to acquire within timeout
}

Full runnable examples can be found in examples/.

Dependencies

Build Environment

This project requires at least the following to build:

• A C++ compiler that conforms to the C++20 standard or greater
• CMake 3.25 or later
• (Test Only) GoogleTest

You can disable building tests by setting CMake option BEMAN_TIMED_LOCK_ALG_BUILD_TESTS to OFF when configuring the project.

Supported Platforms

This project officially supports:

• GCC versions 10–15
• LLVM Clang++ (with libstdc++ or libc++) versions 11–21
• ICX (with libstdc++ or libc++) versions 2021.1.2-2025.2.1
• AppleClang version 17.0.0 (i.e., the latest version on GitHub-hosted macOS runners)
• MSVC version 19.29 (with /std:c++latest) and 19.30 to 19.44.35215.0 (i.e., the latest version on GitHub-hosted Windows runners)
• Note: libstdc++ versions 14-14.3 and 15-15.2 (inclusive) does not support using -fsanitize=thread on code using std::timed_mutex due to Bug 121496. This affects GCC and all implementations using libstdc++ such as LLVM Clang++ and ICX unless -stdlib=libc++ is used.

Note

Versions outside of this range would likely work as well, especially if you're using a version above the given range (e.g. HEAD/ nightly). These development environments are verified using our CI configuration.

Development

Develop using GitHub Codespace

This project supports GitHub Codespace via Development Containers, which allows rapid development and instant hacking in your browser. We recommend using GitHub codespace to explore this project as it requires minimal setup.

Click the following badge to create a codespace:

For more documentation on GitHub codespaces, please see this doc.

Note

The codespace container may take up to 5 minutes to build and spin-up; this is normal.

Develop locally on your machines

For Linux

Beman libraries require recent versions of CMake, we recommend downloading CMake directly from CMake's website or installing it with the Kitware apt library.

A supported compiler should be available from your package manager.

For MacOS

Beman libraries require recent versions of CMake. Use Homebrew to install the latest version of CMake.

brew install cmake

A supported compiler is also available from brew.

For example, you can install the latest major release of Clang as:

brew install llvm

For Windows

To build Beman libraries, you will need the MSVC compiler. MSVC can be obtained by installing Visual Studio; the free Visual Studio 2022 Community Edition can be downloaded from Microsoft.

After Visual Studio has been installed, you can launch "Developer PowerShell for VS 2022" by typing it into Windows search bar. This shell environment will provide CMake, Ninja, and MSVC, allowing you to build the library and run the tests.

Note that you will need to use FetchContent to build GoogleTest. To do so, please see the instructions in the "Build GoogleTest dependency from github.com" dropdown in the Project specific configure arguments section.

Configure and Build the Project Using CMake Presets

This project recommends using CMake Presets to configure, build and test the project. Appropriate presets for major compilers have been included by default. You can use cmake --list-presets to see all available presets.

Here is an example to invoke the gcc-debug preset.

cmake --workflow --preset gcc-debug

Generally, there are two kinds of presets, debug and release.

The debug presets are designed to aid development, so it has debugging instrumentation enabled and many sanitizers enabled.

Note

The sanitizers that are enabled vary from compiler to compiler. See the toolchain files under (cmake) to determine the exact configuration used for each preset.

The release presets are designed for production use, and consequently have the highest optimization turned on (e.g. O3).

Configure and Build Manually

If the presets are not suitable for your use-case, a traditional CMake invocation will provide more configurability.

To configure, build and test the project with extra arguments, you can run this set of commands.

cmake \
  -B build \
  -S . \
  -DCMAKE_CXX_STANDARD=20 \
  -DCMAKE_PREFIX_PATH=$PWD/infra/cmake \
  # Your extra arguments here.
cmake --build build
ctest --test-dir build

Important

Beman projects are passive projects, therefore, you will need to specify the C++ version via CMAKE_CXX_STANDARD when manually configuring the project.

Finding and Fetching GTest from GitHub

If you do not have GoogleTest installed on your development system, you may optionally configure this project to download a known-compatible release of GoogleTest from source and build it as well.

Example commands:

cmake -B build -S . \
    -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=./infra/cmake/use-fetch-content.cmake \
    -DCMAKE_CXX_STANDARD=20
cmake --build build --target all
cmake --build build --target test

The precise version of GoogleTest that will be used is maintained in ./lockfile.json.

Project specific configure arguments

Project-specific options are prefixed with BEMAN_TIMED_LOCK_ALG. You can see the list of available options with:

cmake -LH -S . -B build | grep "BEMAN_TIMED_LOCK_ALG" -C 2

Details of CMake arguments.

BEMAN_TIMED_LOCK_ALG_BUILD_TESTS

Enable building tests and test infrastructure. Default: ON. Values: { ON, OFF }.

You can configure the project to have this option turned off via:

cmake -B build -S . -DCMAKE_CXX_STANDARD=20 -DBEMAN_TIMED_LOCK_ALG_BUILD_TESTS=OFF

[!TIP] Because this project requires GoogleTest for running tests, disabling BEMAN_TIMED_LOCK_ALG_BUILD_TESTS avoids the project from cloning GoogleTest from GitHub.

BEMAN_TIMED_LOCK_ALG_BUILD_EXAMPLES

Enable building examples. Default: ON. Values: { ON, OFF }.

BEMAN_TIMED_LOCK_ALG_INSTALL_CONFIG_FILE_PACKAGE

Enable installing the CMake config file package. Default: ON. Values: { ON, OFF }.

This is required so that users of beman.timed_lock_alg can use find_package(beman.timed_lock_alg) to locate the library.

Integrate beman.timed_lock_alg into your project

To use beman.timed_lock_alg in your C++ project, include an appropriate beman.timed_lock_alg header from your source code.

#include <beman/timed_lock_alg/mutex.hpp>

Note

beman.timed_lock_alg headers are to be included with the beman/timed_lock_alg/ prefix. Altering include search paths to spell the include target another way (e.g. #include <mutex.hpp>) is unsupported.

The process for incorporating beman.timed_lock_alg into your project depends on the build system being used. Instructions for CMake are provided in following sections.

Incorporating beman.timed_lock_alg into your project with CMake

For CMake based projects, you will need to use the beman.timed_lock_alg CMake module to define the beman::timed_lock_alg CMake target:

find_package(beman.timed_lock_alg REQUIRED)

You will also need to add beman::timed_lock_alg to the link libraries of any libraries or executables that include beman.timed_lock_alg headers.

target_link_libraries(yourlib PUBLIC beman::timed_lock_alg)