beman.scope
beman.scope: Generic Scope Guard
beman.scope is a C++ library that provides scope_guard facilities. The library conforms to The Beman Standard.
Implements: D3610R0 Scope Guard targeted at C++29.
Overview
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:
Usage
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/.
Integrate beman.scope into your project
Beman.scope is a header-only library that currently relies on TS implementations for unique_resource and is thus currently available only on g-13 and up, or clang 19 and up -- in C20 mode.
Note that modules support is currently tested only on clang-19 and above and g-15, and is not supported if the C standard is below C23.
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>
//modular version
import beman.scope;With modules import needs to be after any includes to avoid compilation errors.
Building beman.scope
Building is only required to run tests and examples. All compilers build and run include based tests. Compilers known to support modules are automatically detected added to tests.
Build Dependencies
The library itself has no build dependencies other than Catch2 for testing. And for building cmake and ninja. Makefiles are supported in non-modular builds.
Build-time dependencies:
-
cmake -
ninja,make, or another CMake-supported build system-
CMake defaults to "Unix Makefiles" on POSIX systems
-
-
catch2for building tests
License
Source is licensed with the Apache License v2.0 with LLVM Exceptions.
Documentation and associated papers are licensed with the Creative Commons Attribution 4.0 International license.
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.