README.md

beman.scope: Generic Scope Guard

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 see:

• Discourse for discussion of scope

Prior And Other Work

Papers

• TS design and wording paper p0052 - Generic Scope Guard and RAII Wrapper for the Standard Library
• TS adoption paper p1411 - Please reconsider for C++20
• N3677 A Proposal to Add additional RAII Wrappers to the Standard Library
• N4152 uncaught_exceptions - Sutter

Implementations

• GSL final_action - part of core guidelines
• Boost.scope
• scope_guard based on Andrei Alexandrescu and Petru Marginean article
• Windows Implementation Libraries (WIL) - scope_exit
• GCC libstdc++-v3 experimental/scope implementation
• LLVM - ADT/ScopeExit.h
• libcxx - scope_guard.h
• Folly - ScopeGuard.h
• BDE (Bloomberg) - ScopeExit.h

Videos

• Peter Sommerlad - Woes of Scope Guards and Unique_Resource - 5+ years in the making
• Andrei Alexandrescu - Declarative Control Flow

Examples

• TS example of scope_exit

---

beman.scope is a C++ library conforming to The Beman Standard.

Implements: TODO

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

Usage

TODO

Example Usage

TODO

Full runnable examples can be found in examples/.

Building beman.scope

Dependencies

This project has no C or C++ dependencies.

Build-time dependencies:

• cmake
• ninja, make, or another CMake-supported build system
  • CMake defaults to "Unix Makefiles" on POSIX systems

How to install dependencies

Dependencies install scope on Ubuntu 24.04

# Install tools:
apt-get install -y cmake make ninja-build

# Toolchains:
apt-get install                           \
  g++-14 gcc-14 gcc-13 g++-14             \
  clang-18 clang++-18 clang-17 clang++-17

Dependencies install scope on MAC OS $VERSION

# TODO

Dependencies install scope on Windows $VERSION

# TODO

How to build beman.scope

Beman scope is header only.

cmake --workflow --preset gcc-debug
cmake --workflow --preset gcc-release
cmake --install build/gcc-release --prefix /opt/beman.scope

Build beman.scope (verbose logs)

# Configure beman.scope via gcc-debug workflow for development.
$ cmake --workflow --preset gcc-debug
Executing workflow step 1 of 3: configure preset "gcc-debug"

Preset CMake variables:

  CMAKE_BUILD_TYPE="Debug"
  CMAKE_CXX_COMPILER="g++"
  CMAKE_CXX_FLAGS="-fsanitize=address -fsanitize=pointer-compare -fsanitize=pointer-subtract -fsanitize=leak -fsanitize=undefined"
  CMAKE_CXX_STANDARD="20"

TODO

# Run examples.
$ TODO

Install beman.scope (verbose logs)

# Install build artifacts from `build` directory into `opt/beman.scope` path.
$ cmake --install build/gcc-release --prefix /opt/beman.scope
-- Install configuration: "RelWithDebInfo"
-- Up-to-date: /opt/beman.scope/lib/libbeman.exemplar.a
-- Up-to-date: /opt/beman.scope/include/beman/exemplar/identity.hpp


# Check tree.
$ tree /opt/beman.scope
/opt/beman.scope
├── include
│   └── beman
│       └── scope
│           └── scope.hpp


4 directories, 2 files

Disable tests build

To build this project with tests disabled (and their dependencies), simply use BEMAN_EXEMPLAR_BUILD_TESTING=OFF as documented in upstream CMake documentation:

cmake -B build -S . -DBEMAN_EXEMPLAR_BUILD_TESTING=OFF

Integrate beman.scope into your project

Use beman.scope directly from C++

If you want to use beman.scope from your project, you can include beman/scope/*.hpp files from your C++ source files

#include <beman/scope/identity.hpp>

and directly link with libbeman.scope.a

# Assume /opt/beman.scope staging directory.
$ c++ -o identity_usage examples/identity_usage.cpp \
    -I /opt/beman.scope/include/ \
    -L/opt/beman.scope/lib/ -lbeman.exemplar

Use beman.scope directly from CMake

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

find_package(beman.scope REQUIRED)

You will also need to add beman::scope to the link libraries of any libraries or executables that include beman/scope/*.hpp in their source or header file.

target_link_libraries(yourlib PUBLIC beman::scope)

Use beman.scope from other build systems

Build systems that support pkg-config by providing a beman.scope.pc file. Build systems that support interoperation via pkg-config should be able to detect beman.scope for you automatically.

Contributing

Please do! Issues and pull requests are appreciated.