beman.scope is a C++ library provides scope_guard facilities. The library conforms to The Beman Standard.
Implements: D3610R0 Scope Guard targeted at C++29.
Status: Under development and not yet ready for production use.
During the C++20 cycle P0052 Generic Scope Guard and RAII Wrapper for the Standard Library
added 4 types: scope_exit, scope_fail, scope_success
and unique_resource to LTFSv3.
In the intervening time, two standard libraries have implemented support as well as Boost. With the imperative for safety and security in C++ developers need every tool in the toolbox. The authors believe it is time to move this facility into the standard. The paper will re-examine the five year old design and any learning from deployment of the LTFSv3.
For discussions of this library and related work see:
The following is an example of using scope_fail to trigger and action when the scope
is exited with an exception. scope_success and scope_exit provide similar capability
but with different checked conditions on exiting the scope.
#include <beman/scope/scope.hpp>
bool triggered = false;
{
scope_fail guard([&]() { triggered = true; });
// no exception thrown
}
// triggered == false
try {
scope_fail guard([&]() { triggered = true; });
throw std::runtime_error( "trigger failure" );
} catch (...) { // expected }
// triggered == trueunique_resource is a cutomizeable RAII type similar to unique_ptr.
#include <beman/scope/scope.hpp>
{
auto file = beman::scope::unique_resource(
fopen("example.txt", "w"), // function to acquire the FILE*
[](FILE* f) { // function to cleanup on destruction
if (f) {
fclose(f); // Release (cleanup) the resource
}
}
);
// use file via f->
}
// Resource is automatically released when `file` goes out of scope
std::cout << "File has been closed \n";Full runnable examples can be found in examples/.
Beman.scope is a header-only library that currently relies on TS implementations and is thus currently available only on GCC13 and up, or Clang 19 and up -- in C++20 mode.
As a header only library no building is required to use in a project -- simply make
the include directory available add add the following to your source.
#include <beman/scope/scope.hpp>Building is only required to run tests and examples.
The library itself has no build dependencies other than Catch2 for testing and cmake.
Build-time dependencies:
cmakeninja,make, or another CMake-supported build system- CMake defaults to "Unix Makefiles" on POSIX systems
catch2for building tests
cmake --workflow --preset gcc-debug
cmake --workflow --preset gcc-release
cmake --install build/gcc-release --prefix /opt/beman.scopeSource is licensed with the Apache 2.0 license with LLVM exceptions
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
Documentation and associated papers are licensed with the Creative Commons Attribution 4.0 International license.
// SPDX-License-Identifier: CC-BY-4.0
The intent is that the source and documentation are available for use by people how they wish.
The README itself is licensed with CC0 1.0 Universal. Copy the contents and incorporate in your own work as you see fit.
// SPDX-License-Identifier: CC0-1.0
Please do! Issues and pull requests are appreciated.