Document Number: N3677 Date: 2013-04-26 Project: Programming Language C++, Library Working Group Reply-to: Andrew L. Sandoval <sandoval at netwaysglobal dot com>

A Proposal to Add additional RAII Wrappers to the Standard Library

I. Table of Contents

Introduction
Motivation and Scope
Impact on Standard
Design Decisions
Technical Specifications
Acknowledgments
References

II. Introduction

This proposal seeks to add generic RAII wrappers to the standard library. These wrappers will be used to manage the lifetime of various types of resources and to guarantee the execution of code blocks on scope exit. It builds on the concept of smart pointers like unique_ptr, but is designed for use with any type of resource that requires clean-up prior to scope exit, as well as any block of code (via lambda or function invocation) that needs to executed prior to scope exit.

III. Motivation and Scope

Quality C++ code requires the use of RAII to manage all types of resources in order to prevent leakage as well as to limit resource lifetime. Resource leakage can occur from the obvious, though often overlooked, failure to clean-up a resource at its intended end-of-life, as well as the less obvious and arguably more common failure to ensure proper handling of resources during exception unwinding.

Smart pointers such as unique_ptr and shared_ptr provide an excellent means of managing the lifetime of pointer types. Many other RAII classes have been written to manage the lifetime and limit the scope of locks, such as Boost's boost::lock_guard. All of these and the many other types of RAII objects help to substantially improve C++ code quality. This proposal seeks to add a set of generic, light-weight RAII wrappers intended to manage the scope and lifetime of any other type of resource. It also proposes an RAII wrapper intended to wrap a function, lambda, or functor which needs to execute prior to scope exit.

There are many types of resources that may not justify encapsulation in a broader object -- when a simple RAII wrapper around the resource will suffice or will provide a more obvious implementation. This is especially true when object re-use is not expected. In addition, RAII wrappers will simplify the design of objects that do encapsulate resources, allowing the generation of, or the declaration of the resource, to also declare its method of clean-up. This results in moving resource clean-up outside of an explicit destructor, which also assures proper order of destruction when initialization order is correct. This is common practice with pointers managed by unique_ptr and shared_ptr, and even with buffers allocated and managed by vector.

This proposal requests the addition of the following RAII wrapper types:

scoped_function

Executes a function, functor, or lambda on scope exit.
Is generated with make_scoped_function(func);
func is a function, functor, or lambda that takes no parameters. A lambda however may capture and use any scope variables.

scoped_resource_unchecked

Manages a resource's lifetime by executing a deleter function, functor, or lambda on scope exit.
Is generated with make_scoped_resource_unchecked(resource, deleter-func);, or with the more generic make_scoped_resource(resource, deleter-func);
deleter-func is a function, functor, or lambda that takes a single parameter of the same type as resource.
Is suitable for no-fail resources, or other resources in which a validity check by comparison to a no-delete value is not possible.

scoped_resource

Manages a resource's lifetime by executing a deleter function, functor, or lambda on scope exit, when the resource value can be validated by comparison to a no-delete value.
Is generated with make_scoped_resource(resource, deleter-func, no-delete-value);
When generated with make_scoped_resource<true>(resource, deleter-func, no-delete-value); the scoped_resource constructor will throw failed_resource_initialization if the resource is equal to the no-delete value.
deleter-func is a function, functor, or lambda that takes a single parameter of the same type as resource.
no-delete-value is a value of type resource that is used to prevent calling deleter-func when the resource is not valid, as well as to check if the resource is bool valid() const;

unique_resource

Manages a resource's lifetime by executing a constexpr deleter function on scope exit, when the resource value can be validated by comparison to a constexpr no-delete value.
It requires template arguments for:

The type of a constexpr deleter function, which function takes a single parameter of the type of the resource, and from which the resource type is deduced
The constexpr deleter function itself
A bool value, which when set to true will cause the constructor to throw failed_resource_initialization if the value passed to the constructor matches the no-delete value. When false, a validity check is not performed on object construction, but the deleter function will not be executed in the destructor if the validity check fails.
A no-delete value of the deduced type of the resource. The types is deduced from the sole parameter to the deleter-func type. The default no-delete value is static_cast<T>(nullptr).

Because of the static or constexpr non-type template arguments for the deleter function and the no-delete value:

The generated code is very tight and should be roughly the equivalent of adding:
if(resource != nodelete) { deleter-func(resource); } at a common exit point for the scope.
There is no generator function template.
The no-delete value of the same type as the resource. It is used to prevent calling the deleter function if the resource is not valid, as well as to check if the resource is bool valid() const;

Can be constructed without a resource value by using the default constructor. This allows the resource value to be set using operator= at a later time.

A. Motivation for `scoped_function`

scoped_function

Example `scoped_function` for mandatory logging on function exit:

bool SomeFunction(const input_t &input, modifier_t &modifier, status_t &status)
{
    // Always log the status on scope-exit whether it changes or not...
    auto &&log_status_on_exit = std::make_scoped_function([&status, &modifier]() ->void
    {
        LogStatus(status, "SomeFunction", modifier);
    });

    if(!AlterationOne(input, modifier, status))
    {
        return false;
    }
    .
    .
    .
    return AlterationFour(modifier, status);
}

Example `scoped_function` for loop advancement:

LegacyDisassembler dis(pInstructionPointer, length);
while(dis.RemainingBytes())
{
    // Ensure that no matter where else the loop continues, dis gets advanced...
    auto &&advance = std::make_scoped_function([&dis]() ->void
    {
        dis.Advance(dis.InstructionLength());
    });

    if(dis.BadInstruction())
    {
        std::cerr << "Error on " << dis << std::endl;
        continue;   // Skip the bad byte(s)
    }

    // Handle special cases
    .
    .
    .

    // Print the Instruction...
    std::cerr << dis.Address << ": " << dis << std::endl;
}

B. Motivation for `scoped_resource_unchecked`

scoped_resource_unchecked

handles

release()

`scoped_resource_unchecked` example:


CRITICAL_SECTION cs;
InitializeCriticalSection(&cs);
// InitializeCriticalSection() can't fail and returns void, but we need the delete to occur prior to scope exit...
// Otherwise it remains on the process's linked-list of active CRITICAL_SECTION's.
auto &&pCS = std::make_scoped_resource_unchecked(&cs, DeleteCriticalSection);   // DeleteCriticalSection can't fail and return void

C. Motivation for `scoped_resource`

scoped_resource

unique_resource

Example using `scoped_resource` for with a C API:


// Open a file, ensure it is closed when we leave scope, if the file descriptor is valid...
auto&& iFileDesc = std::make_scoped_resource(_open(pszPath, O_WRONLY), _close, -1);	// if _open returns -1, don't call _close...
if(iFileDesc.valid())
{
    _write(iFileDesc, &data, sizeof(data));
}


try
{
    // Open a file, ensure it is closed when we leave scope, if the file descriptor is valid...
    auto&& iFileDesc = std::make_scoped_resource(_open(pszPath, O_WRONLY), _close, -1);	// if _open returns -1, throw...

    _write(iFileDesc, &data, sizeof(data));
}
catch (const std::failed_resource_initialization &e)
{
    std::cout << "Exception: " << e.what() << std::endl;
    return false;
}
return true;

Example using `scoped_resource` for with a Windows API:


// Create or open an event handle, wait on it, but after being signalled close the handle...
// Don't CloseHandle() if we don't have permissions to open it, etc.
// Another exception-free example, that with different calls could be used in kernel-mode
const HANDLE INVALID_EVENT_HANDLE = static_cast<HANDLE>(nullptr);

auto hEvent = std::make_scoped_resource(CreateEvent(nullptr, TRUE, FALSE, nullptr), CloseHandle, INVALID_EVENT_HANDLE);
if(!hEvent.valid())
{
    return false;   // CloseHandle will not be called
}
DWORD dwWait = WaitForSingleObject(hEvent, 1000);
.
.
.
// CloseHandle() will be called as soon as hEvent leaves scope

INVALID_HANDLE_VALUE

-1

CreateFile

NULL

INVALID_HANDLE_VALUE

scoped_ptr

INVALID_HANDLE_VALUE

auto&& hFile = std::make_scoped_resource(CreateFileW(pwzPath, FILE_GENERIC_WRITE, FILE_SHARE_WRITE, nullptr, CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL, nullptr),
    CloseHandle, INVALID_HANDLE_VALUE);     // Compiles fine

std::unique_resource<UNIQUE_DELETER(CloseHandle), INVALID_HANDLE_VALUE> // Compiler error on gcc-4.7, compiles on Visual Studio 2010
    hFile(CreateFileW(pwzPath, FILE_GENERIC_WRITE, FILE_SHARE_WRITE, nullptr, CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL, nullptr));

D. Motivation for `unique_resource`

The primary motivation for using unique_resource over scoped_resource is the size of the generated object code. It's use is restricted to resources that have a constexpr deleter function which takes a single argument of the same type as the resource. Also, the deleter function and the no-delete value must be constant expressions.

There is no generator like make_scoped_resource() for unique_resource. It's construction requires 4 template parameters, but unlike make_scoped_resource(), the static (constexpr) no-delete value has a default value of static_cast<T>(nullptr), where T is the type of the first argument passed to the deleter function.

In the reference implementation unique_resource uses a parent implementation class called unique_resource_impl. This allows the type of the resource to be deduced using template metaprogramming. unique_resource_impl requires 5 template parameters. The TFuncInfo1 template resolves the parameter type of the deleter function for unique_resource which inherits from unique_resource_impl.

To simplify use of unique_resource, a convenience macro is used in the examples below, and in the reference implementation. It is defined as:

#define UNIQUE_DELETER(deleter_fn) decltype(&deleter_fn), deleter_fn, false
#define UNIQUE_DELETER_THROW(deleter_fn) decltype(&deleter_fn), deleter_fn, true

Another consideration when using unique_resource over make_scoped_resource() is the benefit it provides for member variable resources. For example, both of the following classes will accomplish the same end-goal, of calling CloseHandle on m_hEvent when an instance of the class is destroyed, but the unique_resource example is slightly easier to read, especially with the help of UNIQUE_DELETER.

class TestClassMember
{
private:
    // auto &&m_hEvent; // error C3531: 'm_hEvent': a symbol whose type contains 'auto' must have an initializer
    std::scoped_resource<decltype(&CloseHandle), HANDLE> m_hEvent;	// ok, but a bit bulky...  And a macro can't deduce the resource type...

public:
    // TestClassMember() : m_hEvent(std::make_scoped_resource(CreateEvent(nullptr, TRUE, FALSE, nullptr), [](HANDLE hEvent) { if(hEvent) CloseHandle(hEvent); }))
    // {  // ^^: error C2440: 'initializing' : cannot convert from 'std::scoped_resource_unchecked<T,R>' to 'int'
    // }

    TestClassMember() : m_hEvent(std::make_scoped_resource(CreateEvent(nullptr, TRUE, FALSE, nullptr), CloseHandle, static_cast(nullptr)))
    {
        // ^^ This however works, but it isn't quite as easy to follow as the example in TestClassMember2
    }

    void Wait()
    {
        DWORD dwX = WaitForSingleObject(m_hEvent, INFINITE);
        // Other stuff here...
    }

    void Set()
    {
        SetEvent(m_hEvent);
    }

    // Other stuff here...
};

class TestClassMember2
{
private:
    std::unique_resource<UNIQUE_DELETER(CloseHandle)> m_hEvent;
    // ^^ This is easy to understand, ^^ draws attention to the deleter function

public:
    TestClassMember2() : m_hEvent(CreateEvent(nullptr, TRUE, FALSE, nullptr))   // Initialization is natural, similar to the raw resource type
    {
    }

    void Wait()
    {
        DWORD dwX = WaitForSingleObject(m_hEvent, INFINITE);
        // Other stuff here...
    }

    void Set()
    {
        SetEvent(m_hEvent);
    }
    // Other stuff here...
};

Example of `unique_resource` compared to a `scoped_resource` generated with `make_scoped_resource()`

test_unique_resource()

test_scoped_resource()


void test_unique_resource(...)    //... added to prevent inlining
{
    // Create an event which will be closed on scope-exit, if NOT NULL.  It can be passed to SetEvent/WFSO as hEvent
    std::unique_resource<UNIQUE_DELETER(CloseHandle)> hEvent(CreateEvent(nullptr, TRUE, FALSE, nullptr));
}

// Object Code: (32 bytes, no prologue, no epilogue, 1 byte for ret)
// scope_exit!test_unique_resource [scope_exit\scope_exit.cpp @ 243]:
//   243 003d1310 6a00            push    0
//   245 003d1312 6a00            push    0
//   245 003d1314 6a01            push    1
//   245 003d1316 6a00            push    0
//   245 003d1318 ff1510303d00    call    dword ptr [scope_exit!_imp__CreateEventW (003d3010)]
//   246 003d131e 85c0            test    eax,eax
//   246 003d1320 7407            je      scope_exit!test_unique_resource+0x19 (003d1329)
//   246 003d1322 50              push    eax
//   246 003d1323 ff1514303d00    call    dword ptr [scope_exit!_imp__CloseHandle (003d3014)]
//   246 003d1329 c3              ret

///////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////

const HANDLE INVALID_EVENT_HANDLE = static_cast<HANDLE>(nullptr);
void test_scoped_resource(...)    //... added to prevent inlining
{
    // Create an event which will be closed on scope-exit, if NOT NULL.  It can be passed to SetEvent/WFSO as hEvent
    auto hEvent = std::make_scoped_resource(CreateEvent(nullptr, TRUE, FALSE, nullptr), CloseHandle, INVALID_EVENT_HANDLE);
}

// Object Code: (57 bytes, 3 prologue bytes and 3 epilogue bytes, to allow for scoped_resource (12 bytes, aligned) on the stack, + 1 for ret)
// scope_exit!test_scoped_resource [scope_exit.cpp @ 250]:
//   250 003d1330 55              push    ebp
//   250 003d1331 8bec            mov     ebp,esp
//   250 003d1333 83ec0c          sub     esp,0Ch
//   252 003d1336 6a00            push    0
//   252 003d1338 6a00            push    0
//   252 003d133a 6a00            push    0
//   252 003d133c 6a01            push    1
//   252 003d133e 6a00            push    0
//   252 003d1340 ff1510303d00    call    dword ptr [scope_exit!_imp__CreateEventW (003d3010)]
//   252 003d1346 8b0d14303d00    mov     ecx,dword ptr [scope_exit!_imp__CloseHandle (003d3014)]
//   252 003d134c 8bd0            mov     edx,eax
//   252 003d134e 8d45f4          lea     eax,[ebp-0Ch]
//   252 003d1351 e83a060000      call    scope_exit!std::make_scoped_resource<int (__stdcall*)(void *),void *> (003d1990)
//   253 003d1356 8b45f8          mov     eax,dword ptr [ebp-8]
//   253 003d1359 83c404          add     esp,4
//   253 003d135c 3b45fc          cmp     eax,dword ptr [ebp-4]
//   253 003d135f 7404            je      scope_exit!test_scoped_resource+0x35 (003d1365)
//   253 003d1361 50              push    eax
//   253 003d1362 ff55f4          call    dword ptr [ebp-0Ch]
//   253 003d1365 8be5            mov     esp,ebp
//   253 003d1367 5d              pop     ebp
//   253 003d1368 c3              ret

Reference Implementation

http://www.andrewlsandoval.com/scope_exit/scoped_resource.h : <scoped_resource> header file
http://www.andrewlsandoval.com/scope_exit/scope_exit.cpp : scope_exit.cpp file with tests

Compiles on Windows x86 and x64, using Visual Studio 2010+ and MinGW g++ 4.7
Should compile on other platforms if Windows specific APIs are not used

Scope

scoped_resource

unique_ptr

Final Notes on Motivations and Scope:

IV. Impact on Standard

<scope_resource>

<utility>

std::move

<type_traits>

std::remove_pointer

std::add_reference

V. Design Decisions

A. General Principles

Simplicity

Using an RAII resource wrapper should be as easy as using a raw data type. Generally the cast operator accomplishes this goal. The get() method would be a reasonable alternative to the cast operator if it were to meet with insurmountable opposition. Other operators are also provided to simplify usage in a natural manner for the wrapped resource.

Simple construction and generation should encourage use of the wrappers over raw resource types. This is as true when resources are used within functions and methods as it is when the wrappers are used in objects designed to encapsulate and provided additional related functionality around the resource in a class.

The "generator" function templates make_scoped_function, and make_scoped_resource help ensure simplicity.

Though macros are generally frowned upon, the UNIQUE_DELETER macro used to simplify the passing of template parameters to unique_resource, can also claim to improve simplicity. Unlike other macros, it does not hide functionality -- instead it draws attention to the the template arguments that matter most. The end result is a very easy to use and understand unique_resource.

Code written with these RAII wrappers becomes simple to maintain. Lifetime of resources and their method of clean-up is evident from the time of declaration or generation. The order of operations in clean-up is expected and simple. And object lifetime is managed by scope rather than the hopefully correct ordering of clean-up at scope-exit or in traditional destructors.

Transparency

It should be obvious from a glance what each RAII resource wrapper does. Constructors and generator function templates should clearly show the binding of the resource's clean-up to the resource. Similarly a glance at a scoped_function should make it obvious what will happen when the object reaches scope exit.

Resource Conservation and Lifetime Management

Each wrapper is designed to encourage consideration of a resource's lifetime when it is created. The cost of using these wrappers should not out weigh the benefits.

Generated Object Code Size

Code bloat should be avoided, and options should exist to minimize generated object code size. These wrappers should be usable in resource constrained environments.

Exception Safety

These RAII resource wrappers should be able to be used without introducing any new risk of throwing exceptions due to allocation failures, etc. They should be usable for example in kernel code where C++ exceptions often can't be handled.

Both types of RAII wrappers that allow for a vailidity check (scoped_resource, and unique_resource) default to a nothrow implementation. Each also offer a simple means by which failed_resource_initialization may be thrown on construction when a validity check fails. This provides the broadest opportunity for use, and adaptation to the users needs.

Use of Lambdas

These RAII resource wrappers should allow for the use of lambdas with and without capturing. Because lambda's may be used to capture by reference, these RAII wrappers can utilize or update references just prior to scope-exit, etc. Lambda's also provide a means of adding logic to deleter "functions", and of returning status from a deleter function.

B. Prior implementations

RAIIFunction and RAIIWrapper

RAIIFunction and RAIIWrapper have been in shipping commercial products. They were initially posted to std-proposals to begin the discussion leading to this proposal. RAIIWrapper is very similar to unique_resource. RAIIFunction was original designed to inherit from std::function<void ()>, and was later changed to use the same in composition. This class was posted to the Boost Developer mailing list, where encouragement and feedback where given on possible inclusion in Boost. It was noted however that std::function can throw on an allocation failure. This was mentioned when posting to the std-proposals list, and the current solution -- of using template types (and generator function templates) instead of std::function<void ()> was recommended by one of the list participants (DeadMG). scoped_function, scoped_resource_unchecked, and scoped_resource along with their make_scoped_function and make_scoped_resource() generators are the result of reworking RAIIFunction based on feedback from the group in general. The result is a much more usable set of classes, where lambda's can be used to clean-up resources with or without capturing, etc.

Boost Scope.Exit

During discussion on the Boost Developer mail list, attention was drawn to the Boost Scope.Exit library. This library uses macros to provide the ability to execute clean-up code on scope exit. For the purposes of this proposal, macros have been avoided, other than the very simple UNIQUE_DELETER macro that is used only for template parameters. Macros often hide details, including from debuggers, that can be crucial to understand and troubleshooting problems. For that reason, and because of the general distaste for macros in C++, Boost Scope.Exit was not considered for this proposal. That should not be in anyway interpreted as disrespect to the author of Boost Scope.Exit, as it was designed to work with earlier C++ compilers that lack C++11 support. It should also be noted that the Boost Scope.Exit documentation also includes a suggested alternative for a class compositing std::function<void (void)>₁.

std::unique_ptr

During discussions on the std-proposal list, many examples were given, and some suggestions that std::unique_ptr is sufficient and additional RAII classes are not needed. This proposal rejects those suggestions. Though std::unique_ptr is vital to the Standard Library it is designed to work with pointers, not resources of other types. Converting resources, whether they are int's of a file descriptors, or other non-pointer types isn't straightforward -- and requires that the deleter be able to dereference the pointer. That would rule out use with many functions, unless the deleter function was first wrapped in a lambda or another function or functor for that purpose. Additionally, std::unique_ptr does not provide a cast operator to allow natural use of the wrapped resource in API calls, etc.

ScopeGuard

An article₂ written by Andrei Alexandrescu and Petru Marginean, published by Dr. Dobbs Magazine in December 2000 introduces a class called ScopeGuard, which is very similar to scope_resource_uc as presented in the reference implementation associated with this proposal.

C. Risks

The cast operator provided by each of the classes does pose a minor risk. For example, if a confused user where to try to to mix the make_scoped_resource() call with construction of a unique_resource, the cast operator will allow initialization of unique_resource, but the return of the make_scoped_resource() will result in a temporary object, which after transfering the wrapped resource to the unique_resource will then be "deleted" by the deleter function passed to make_scoped_resource. This would lead to the deleter being invoked more than once, and the resource being used after deletion. This is a minor risk. The template parameters to unique_resource should make it obvious that it does not match up to make_scoped_resource().

VI. Technical Specifications

Header

Table 44 — General utilities library summary
Subclause	Header(s)
20.14 Scoped resources	`<scoped_resource>`

20.14 Scoped resources

20.14.1 Class template `scoped_function`

1	A scoped function is an object s that manages a function object f such that f will be invoked when s is destroyed (e.g., when leaving block scope (6.7)).
2	The function object managed by `scoped_function<T>` takes no parameters, so that s may invoke f as `f();`.
3	f may be a function pointer, functor, callable function as returned from `std::bind`, or a lambda taking no parameters.


namespace std
{
    template<typename T> class scoped_function
    {
    public:
        // 20.14.1.1 constructors
        explicit scoped_function(T&& f) noexcept;
        explicit scoped_function(const T& f) noexcept;

        // 20.14.1.2 destructor
        ~scoped_function();

        // 20.14.1.3 modifiers
        scoped_function& release() noexcept();
        scoped_function& reset(T&& f);
        scoped_function& reset(const T& f);
        scoped_function& invoke(bool bRelease = true);
        void operator()();

        // 20.14.1.4 assignment
        void operator=(T&& f) noexcept;
        void operator=(const T& f) noexcept;
    };

    // 20.14.1.5 generator
    // Make a scoped_function
    // Takes 1 parameter - the function to be run on scope exit...
    template<typename T> scoped_function<T> make_scoped_function(T f) noexcept;
    {
        return scoped_function<T>(std::move(f));
    }
}

20.14.1.1 scoped_function constructors

scoped_function

std::make_scoped_function( f )

scoped_function

//
// Using a lambda:
auto logOnScopeExit = std::make_scoped_function([&syslog, &someStateVariable]() ->void
{
    syslog << "Exiting with state: " << someStateVariable;
});

//
// Using a function:
// e.g. void SetFinalStatus();
auto setFinalStatus = std::make_scoped_function(SetFinalStatus);

//
// Using bind
auto closeFile = std::make_scoped_function( std::bind(close, fd) );     // std::bind may throw

20.14.1.2 scoped_function's destructor

scoped_function

release()

invoke(true)

20.14.1.3 scoped_function's modifiers

release() instructs scoped_function that the function passed to the constructor (or reset / assignment operators) is not to be called when the destructor is invoked.
reset() accepts a new function, function object, or lambda to be called when the scoped_function destructor is invoked. The argument is the same as what is accepted by the constructors. Reseting the function also resets the state of a previously "released" scoped_function
invoke(true) performs an early (pre-destructor) invocation of the function passed to the constructor, reset method, or assignment operator. The default true parameter sets the scoped_function to the "released" state so that the function will not be invoked again when the destructor is called.
invoke(false) performs an early (pre-destructor) invocation of the function passed to the constructor, reset method, or assignment operator. The false parameter leaves the scoped_function in the "unreleased" state so that the function will be invoked again when the destructor is called.
operator()() performs an early (pre-destructor) invocation of the function passed to the constructor, the same as if invoke(true) had been called.

20.14.1.4 scoped_function's assignment operators

reset()

release()

invoke(true)

20.14.1.5 `make_scoped_function`

make_scoped_function(func)

scoped_function

20.14.2 Class template `scoped_resource_unchecked`

1	A scoped_resource_unchecked is an object s that manages a generic resource r such that a clean-up function, function object, or lambda, f(r) will be invoked when s is destroyed (e.g., when leaving block scope (6.7)).
2	The function object f managed by `scoped_resource_unchecked<TDel, TRes>` takes a single parameter of the type of the resource r so that s may invoke f(r) as `f(r);`, when s leaves the current scope.
3	f may be a function pointer, functor, a callable function as returned from `std::bind`, or a lambda, taking a single argument of the type of the resource.
4	r may be accessed through cast operators as if it were of the type of the resource r.
5	Unlike scoped_resource, r is not compared to a "no-delete value" prior to the invocation of `f(r)`.
6	A `scoped_resource_unchecked` may be generated (is intended to be generated) using `make_scoped_resource(r, f)`


namespace std
{
    template<typename TDel, typename TRes> class scoped_resource_unchecked
    {
    public:
        // 20.14.2.1 constructors
        explicit scoped_resource_unchecked(TDel&& arg, TRes&& resource) noexcept;
        explicit scoped_resource_unchecked(const TDel& arg, const TRes& resource) noexcept;

        // 20.14.2.2 destructor
        ~scoped_resource_unchecked();

        // 20.14.2.3 modifiers
        TRes release() throw();
        scoped_resource_unchecked& reset(TRes&& resource);
        scoped_resource_unchecked& reset(const TRes& resource);
        scoped_resource_unchecked& invoke(bool bRelease = true);
        void operator()();

        // 20.14.2.4 access
        TRes get() const throw();
        operator TRes() const throw();
        TRes operator->() const;
        TRes* operator&();
        TDel& get_deleter();
        const TDel& get_deleter() const;
    };

    // 20.14.2.5 Specific Generator
    // Make a scoped_resource_unchecked (unchecked)
    // Takes 2 arguments: The resource and the deleter
    template<typename TDel, typename TRes>
    scoped_resource_unchecked<TDel, TRes> make_scoped_resource_unchecked(TRes r, TDel d) throw()    // Specific request
    {
        return scoped_resource_unchecked<TDel, TRes>(std::move(d), std::move(r));
    }

    // 20.14.2.6 Generic Generator
    template<typename TDel, typename TRes>
    scoped_resource_unchecked<TDel, TRes> make_scoped_resource(TRes r, TDel d) throw()              // Generic request
    {
        return scoped_resource_unchecked<TDel, TRes>(std::move(d), std::move(r));
    }
}

20.14.2.1 scoped_resource_unchecked constructors

scoped_resource_unchecked

std::make_scoped_resource(resource, deleter)

scoped_resource_unchecked

//
// Most common usage - close "handle" types on scope-exit, using a function...
extern PACCESS_TOKEN PsReferencePrimaryToken(IN PEPROCESS pProcess);    // Assumption: Always returns a valid value that can be passed to ObDerferenceToken
extern void ObDereferenceToken(PACCESS_TOKEN pToken);                   // Deleter: Handles any value (including nullptr) from PsReferencePrimaryToken()

// Manual Construction (not intended):
std::scoped_resource_unchecked<decltype(&ObDereferenceToken), PACCESS_TOKEN> pToken(PsReferencePrimaryToken(PsGetCurrentProcess(), ObDereferenceToken));

// Construction via Generic Generator (preferred method) (see 20.14.2.6):
auto pToken = std::make_scoped_resource(PsReferencePrimaryToken(PsGetCurrentProcess(), ObDereferenceToken));

//
// Using a lambda:
extern PACCESS_TOKEN PsReferencePrimaryToken(IN PEPROCESS pProcess);    // Assumption: Always returns a valid value that can be passed to ObDerferenceToken
extern void ObDereferenceObject(PVOID pObject);                         // Generic deleter
auto pToken = std::make_scoped_resource(PsReferencePrimaryToken(PsGetCurrentProcess()), [](PACCESS_TOKEN pToken) ->void
{
    if(pToken == nullptr)
    {
        syslog << "Warning, closing nullptr primary token on scope-exit!!!";
    }
    ObDereferenceObject(pToken);
});

//
// Using bind
extern void * VirtualAllocGuaranteed(PVOID pPreferredBaseAddr, size_t szSize, unsigned int flags, unsigned int pageProtection);  // System API that always returns usable pointer (even if nullptr / page zero)
extern void VirtualFree(void *pAddress, size_t size, unsigned int freeFlags);       // Generic System API for releasing, freeing, etc. virtual memory

auto pVirtMem = std::make_scoped_resource(VirtualAllocGuaranteed(nullptr, 4096, MEM_COMMIT|MEM_RESERVE, PAGE_READWRITE),
    std::bind(VirtualFree, _1, 0, MEM_RELEASE));

20.14.2.2 scoped_resource_unchecked's destructor

scoped_resource_unchecked

release()

invoke(true)

20.14.2.3 scoped_resource_unchecked's modifiers

release() prevents the scoped_resource_unchecked from invoking the "deleter" function in the destructor. It returns a copy of the resource so that it may if needed, be assigned to another tracking object.
reset(resource) causes the scoped_resource_unchecked to invoke the "deleter" function for any currently tracked resource that has not been "released", and assigns a new resource to the scoped_resource_unchecked to be tracked. The scoped_resource_unchecked will be set to an "un-released" state when a new resource is assigned.
invoke(true) performs an early (pre-destructor) invocation of the "deleter" function. The default true parameter sets the scoped_resource_unchecked to the "released" state so that the deleter function will not be invoked again when the destructor is called, unless the object is subsequently "reset."
invoke(false) performs an early (pre-destructor) invocation of the "deleter" function. The false parameter leaves the scoped_resource_unchecked in the "un-released" state so that the deleter function will be invoked again when the destructor is called.
operator()() performs an early (pre-destructor) invocation of the deleter function, the same as if invoke(true) had been called.

20.14.2.4 scoped_resource_unchecked's accessors

TRes get() const throw() returns the resource being managed by the scoped_resource_unchecked object.
operator TRes() const throw() returns the resource being managed by the scoped_resource_unchecked object.
TRes operator->() const returns the resource being managed by the scoped_resource_unchecked object.
TRes* operator&() returns a pointer to the resource being managed by the scoped_resource_unchecked object, where the scoped_resouce_unchecked has a private member of type TRes such as TRes m_resource; which is returned from this accessor with return &m_resource;
TDel& get_deleter() returns a reference to the deleter function. This allows the caller to modify the deleter function if needed on a non-const object.
const TDel& get_deleter() const returns a reference to the deleter function.

20.14.2.5 `make_scoped_resource_unchecked`

make_scoped_resource_unchecked(resource, deleterfunc)

scoped_resource_unchecked

20.14.2.6 `make_scoped_resource`

make_scoped_resource(resource, deleterfunc)

scoped_resource_unchecked

scoped_resource

scoped_resource_unchecked

scoped_resource

throw failed_resource_initialization();

20.14.3 Addition of `std::failed_resource_initialization exception`

scoped_resource

unique_resource


namespace std
{
    ////////////////////////////////////////////////////////////////////////////
    // failed_resource_initialization
    // An exception thrown when a no-delete value is passed to a scoped_resource
    // or unique_resource constructor, assignment, or reset IF the template
    // arguments allow for throwing.  Throwing is optional so that these classes
    // may be used in environment where exception can not be handled (e.g.
    // kernel drivers, etc.)  In those cases the resource should be validated
    // using .valid() prior to use.
    ////////////////////////////////////////////////////////////////////////////
    class failed_resource_initialization : public exception
    {
    public:
        explicit failed_resource_initialization(const char * = nullptr) throw()
        {
        }

        virtual const char * what() const throw()
        {
            return "resource initialization failed";
        }
    };
}

20.14.4 Class template `scoped_resource`

1	A scoped_resource is an object s that manages a generic resource r such that a clean-up function, function object, or lambda, f(r) will be invoked when s is destroyed (e.g., when leaving block scope (6.7)), as long as the resource passes a validity check.
2	The function object f managed by `scoped_resource<TDel, TRes, const bool throw_on_init_failure = false>` takes a single parameter of the type of the resource r so that s may invoke f(r) as `f(r);`, when s leaves the current scope or is otherwise destructed.
3	f may be a function pointer, functor, a callable function as returned from `std::bind`, or a lambda, taking a single argument of the type of the resource.
4	r may be accessed through cast operators as if it were of the type of the resource r.
5	Unlike scoped_resource_unchecked, r is compared to a "no-delete value" prior to the invocation of `f(r)`.
6	A `scoped_resource` may be generated (is intended to be generated) using `make_scoped_resource(r, f, nd)`
7	The 3rd template parameter, when true, allows the constructors to throw if the resource matches the "invalid" or "no-delete" value.


namespace std
{
    template<typename TDel, typename TRes, const bool throw_on_init_failure> class scoped_resource
    {
    public:
        // 20.14.4.1 constructors
        explicit scoped_resource(TDel&& arg, TRes&& resource, TRes no_delete_value);
        explicit scoped_resource(const TDel& arg, const TRes& resource, TRes no_delete_value);

        // 20.14.4.2 destructor
        ~scoped_resource();

        // 20.14.4.3 modifiers
        TRes release() throw();
        scoped_resource& reset(TRes&& resource);
        scoped_resource& reset(const TRes& resource);
        scoped_resource& invoke(bool bRelease = true);
        void operator()();

        // 20.14.4.4 access
        TRes get() const throw();
        operator TRes() const throw();
        TRes operator->() const;
        TRes* operator&();
        TDel& get_deleter();
        const TDel& get_deleter() const;

        // 20.14.4.5 validity checking
        bool valid() const throw();
    };

    // 20.14.4.6 Default Generator Function
    // Takes 3 parameters: The Resource, the Deleter, and a "invalid" or "no-delete" value
    template<typename TDel, typename TRes>
    scoped_resource<TDel, TRes, false> make_scoped_resource(TRes resource, TDel deleter, TRes nodelete)
    {
       return scoped_resource<TDel, TRes, false>(std::move(deleter), std::move(resource), std::move(nodelete));
    }

    // 20.14.4.7 Generator Function for throw_on_init
    template<bool t_throw_on_init_failure, typename T, typename R>
    scoped_resource<T, R, t_throw_on_init_failure> make_scoped_resource(R r, T t, R nd)
    {
       return scoped_resource<T, R, t_throw_on_init_failure>(std::move(t), std::move(r), std::move(nd));
    }
}

20.14.4.1 scoped_resource constructors

scoped_resource

The deleter function - a callable function (or lambda) taking a single parameter of the type of the second template argument.
The resource to be managed / tracked by the scoped_resource.
A no-delete or "invalid" value of the type of the resource which may be used for comparision to:
- Prevent calling the deleter function in the destructor, when the resource has an invalid value (e.g. -1 for a file descriptor).
- Allow a comparision for the valid() method.
- Allow a comparision for when throwing an exception is enabled in the constructor when passed an invalid value.

std::make_scoped_resource(resource, deleter, nodelete)

scoped_resource

//
// Most common usage - close "handle" types on scope-exit, using a function...
extern HANDLE CreateEventW(PSECURITY_ATTRIBUTES pEventAttributes, BOOL bManualReset, BOOL bInitialState, PCWSTR pName);
extern void CloseHandle(HANDLE h);
extern int open(const char *pszFilename, int oflags, ...);
extern void close(int iFileDesc);

// Construction via Generic Generator with nullptr check, no-throw option
auto hEvent = std::make_scoped_resource(CreateEvent(nullptr, FALSE, FALSE, nullptr), CloseHandle, nullptr);
if(hEvent.valid()) // After Initialization check if (hEvent == nullptr)

//
// Construction via Generic Generator with nullptr check, throw on allocation failure...
try
{
    auto hEvent = std::make_scoped_resource<true>(CreateEvent(nullptr, FALSE, FALSE, nullptr), CloseHandle, nullptr);
}
catch (const std::failed_resource_initialization &e)
{
    // Deal with failure to CreateEvent, IOW hEvent == nullptr
}

//
// Construction via Generic Generator with -1 check, no-throw option
auto iFileDesc = std::make_scoped_resource(open("/tmp/log.txt", O_WRONLY|O_APPEND), close, -1);
if(iFileDesc.valid()) // Check validity
{
    write(iFileDesc, ...);
}

//
// Construction via Generic Generator with -1 check, throw on allocation failure
try
{
    auto iFileDesc = std::make_scoped_resource<true>(open("/tmp/log.txt", O_WRONLY|O_APPEND), close, -1);
    write(iFileDesc, ...);  // Can't get here if allocation failed
}
catch (const std::failed_resource_initialization &e)
{
    // Deal with failure to open file, IOW iFileDesc == -1
}

scoped_resource

scoped_resource_unchecked

scoped_resource

20.14.4.2 scoped_resource_unchecked's destructor

scoped_resource

release()

invoke(true)

20.14.4.3 scoped_resource's modifiers

release() prevents the scoped_resource from invoking the "deleter" function in the destructor. It returns a copy of the resource so that if needed it may be assigned to a new tracking object, such as a scoped_resource within a different scope.
reset(resource) causes the scoped_resource to invoke the "deleter" function for any currently tracked and valid resource that has not been "released", and assigns a new resource to the scoped_resource to be tracked. The scoped_resource will be set to the "un-released" state when a new resource is assigned. The deleter function does not change. If the scoped_resource was constructed with the throw-option, the new resource will be compared to the no-delete value passed to the constructor and std::failed_resource_initialization exception will be thrown if it matches.
invoke(true) performs an early (pre-destructor) invocation of the "deleter" function for a valid resource. The default true parameter sets the scoped_resource to the "released" state so that the deleter function will not be invoked again when the destructor is called, unless the object is subsequently "reset."
invoke(false) performs an early (pre-destructor) invocation of the "deleter" function for a valid resource. The false parameter leaves the scoped_resource in the "un-released" state so that the deleter function will be invoked again when the destructor is called.
operator()() performs an early (pre-destructor) invocation of the deleter function, the same as if invoke(true) had been called.

20.14.4.4 scoped_resource accessors

TRes get() const throw() returns the resource being managed by the scoped_resource object.
operator TRes() const throw() returns the resource being managed by the scoped_resource object.
TRes operator->() const returns the resource being managed by the scoped_resource object.
TRes* operator&() returns a pointer to the resource being managed by the scoped_resource object, where the scoped_resouce has a private member of type TRes such as TRes m_resource; which is returned from this accessor with return &m_resource;
TDel& get_deleter() returns a reference to the deleter function. This allows the caller to modify the deleter function if needed on a non-const object.
const TDel& get_deleter() const returns a reference to the deleter function.

20.14.4.5 scoped_resource validity checking

valid()

scoped_resource

20.14.4.6 `make_scoped_resource - Default Generator Function`

make_scoped_resource_unchecked(resource, deleterfunc, no_delete_value)

scoped_resource

if(resource == no_delete_value)

valid()

scoped_resource

20.14.4.7 `make_scoped_resource<true> - Generator Function which allows throws on allocation failure`

make_scoped_resource_unchecked<bool>(resource, deleterfunc, no_delete_value)

scoped_resource

std::failed_resource_initialization

if(resource == no_delete_value)

20.14.5 Class template `unique_resource`

1	A unique_resource is an object s that manages a generic resource r such that a static clean-up function, f(r) will be invoked when s is destroyed (e.g., when leaving block scope (6.7)), as long as the resource passes a validity check.
2	The clean-up function f managed by `unique_resource` takes a single parameter of the type of the resource r so that s may invoke f(r) as `f(r);`, when s leaves the current scope or is otherwise destructed.
3	f must be a function that can be passed and invoked as a template argument, known at compile time. The no-delete value must also be a static value that may be passed and evaluated as a template argument. This allows the compiler to generate the least possible amount of code for each `unique_resource`.
4	r may be accessed through cast operators as if it were of the type of the resource r.
5	Like scoped_resource, r is compared to a "no-delete value" prior to the invocation of `f(r)`.
6	There is no generator for `unique_resource`. It is designed for use in places where a generator is not convenient, and where the smallest generated code possible is needed.
7	The 3rd template parameter, when true, allows the constructors to throw if the resource matches the "invalid" or "no-delete" value.
8	Convenience macros are provided to simplify the declaration of template parameters.
9	As shown below, the reference implementation uses an implementation-defined class and a set of implementation defined helper classes to aid in deducing template parameters. While these classes are not part of the specification, the interfaces they expose must be carried forward to the actual `unique_resource` implementation which in this case inherits from the base class.


namespace std
{
    // 20.14.5.1 unique_resource_impl
    template<typename TResource, typename TDeleter, TDeleter t_deleter, bool throw_on_init_failure, TResource t_nodelete>
    class unique_resource_impl
    {
    private:
        unique_resource_impl(const unique_resource_impl &);
        void operator=(const unique_resource_impl &);

    public:
        unique_resource_impl() : m_resource(t_nodelete)    // Allows for operator=(TResource) later...
        {
        }

        explicit unique_resource_impl(TResource&& resource) : m_resource(std::move(resource))
        {
            if(throw_on_init_failure && t_nodelete == m_resource)
            {
                throw failed_resource_initialization();
            }
        }

        explicit unique_resource_impl(const TResource& resource) : m_resource(resource)
        {
            if(throw_on_init_failure && t_nodelete == m_resource)
            {
                throw failed_resource_initialization();
            }
        }

        ~unique_resource_impl()
        {
            invoke(true);
        }

        TResource release() throw()
        {
            TResource tempcopy = m_resource;
            m_resource = t_nodelete;
            return tempcopy;
        }

        unique_resource_impl& reset(TResource&& resource)
        {
            invoke(false);        // false because we are going to change it manually here...
            m_resource = std::move(resource);
            if(throw_on_init_failure && t_nodelete == m_resource)
            {
                throw failed_resource_initialization();
            }
            return *this;
        }

        unique_resource_impl& reset(TResource const& resource)
        {
            invoke(false);        // false because we are going to change it manually here...
            m_resource = resource;
            if(throw_on_init_failure && t_nodelete == m_resource)
            {
                throw failed_resource_initialization();
            }
            return *this;
        }

        void operator()()
        {
            invoke(true);
        }

        TResource get() const throw()
        {
            return m_resource;
        }

        void operator=(TResource &&res)
        {
            reset(res);
        }

        void operator=(TResource const &res)
        {
            reset(res);
        }

        //
        // Cast operator - for access to resource
        // WARNING: This can cause make_scoped_resource*(R, T) to return a temporary that initializes something else!  Be careful with usage!
        // Nevertheless, it provides transparency for API calls, etc.
        operator TResource() const throw()
        {
            return m_resource;
        }

        //
        // operator-> for accessing members on pointer types
        TResource operator->() const
        {
            return m_resource;
        }

        //
        // operator& for getting the address of the resource - not const!
        TResource* operator&()
        {
            return &m_resource;
        }

        const TDeleter get_deleter() const
        {
            return t_deleter;
        }

        //
        // invoke...(e.g. early invocation), allows for repeated
        // invocation, if bRelease = false.  Use with caution!
        unique_resource_impl& invoke(bool bRelease = true)
        {
            if(valid())
            {
                t_deleter(m_resource);
                if(bRelease)
                {
                    m_resource = t_nodelete;
                }
            }
            return *this;
        }

        //
        // Check for a valid / usable resource
        bool __inline valid() const throw()
        {
            return m_resource != t_nodelete;
        }
    };

    // 20.14.5.2 implementation specific helper classes used to deduce template parameters
    //
    // Extract First Parameter Type
    //
    template <typename T>
    struct TFuncInfo1;

    #if defined(_WIN32) && !defined(_WIN64)        // Support Microsoft calling conventions
    template <typename TReturn, typename TParam>
    struct TFuncInfo1<TReturn (__stdcall *)(TParam)>
    {
        typedef TReturn tReturnType;
        typedef TParam tParameter1;
    };

    template <typename TReturn, typename TParam>
    struct TFuncInfo1<TReturn (__cdecl *)(TParam)>
    {
        typedef TReturn tReturnType;
        typedef TParam tParameter1;
    };

    template <typename TReturn, typename TParam>
    struct TFuncInfo1<TReturn (__fastcall *)(TParam)>
    {
        typedef TReturn tReturnType;
        typedef TParam tParameter1;
    };
    #else    // All other compilers
    template <typename TReturn, typename TParam>
    struct TFuncInfo1<TReturn (*)(TParam)>
    {
        typedef TReturn tReturnType;
        typedef TParam tParameter1;
    };
    #endif    // _WIN32 && !_WIN64

    // 20.14.5.3 unique_resource (reference implementation)
    template<typename TDeleter,
        TDeleter t_deleter,
        bool throw_on_init_failure = false,        // Set to true if you want throw(failed_resource_initialization) when m_resource == t_nodelete_value
        typename TFuncInfo1<TDeleter>::tParameter1 t_nodelete_value = static_cast<typename TFuncInfo1<TDeleter>::tParameter1>(nullptr)>
    struct unique_resource : public
        unique_resource_impl<typename TFuncInfo1<TDeleter>::tParameter1, TDeleter, t_deleter, throw_on_init_failure, t_nodelete_value> 
    {
        typedef typename TFuncInfo1<TDeleter>::tParameter1 TResource;

        unique_resource() : 
            unique_resource_impl<typename TFuncInfo1<TDeleter>::tParameter1, TDeleter, t_deleter, throw_on_init_failure, t_nodelete_value>()
        {
        }

        unique_resource(TResource &&resource) : 
            unique_resource_impl<typename TFuncInfo1<TDeleter>::tParameter1, TDeleter, t_deleter, throw_on_init_failure, t_nodelete_value>(std::move(resource))
        {
        }

        unique_resource(TResource const &resource) : 
            unique_resource_impl<typename TFuncInfo1<TDeleter>::tParameter1, TDeleter, t_deleter, throw_on_init_failure, t_nodelete_value>(resource)
        {
        }

        void operator=(TResource &&resource)
        {
            this->reset(resource);
        }

        void operator=(TResource const &resource)
        {
            this->reset(resource);
        }
    };

    //
    // 20.14.5.4 unique_resource (specification)
    template<typename TDeleter,
        TDeleter t_deleter,
        bool throw_on_init_failure = false,        // Set to true if you want throw(failed_resource_initialization) when m_resource == t_nodelete_value
        typename TFuncInfo1<TDeleter>::tParameter1 t_nodelete_value = static_cast<typename TFuncInfo1<TDeleter>::tParameter1>(nullptr)>
    class unique_resource 
    {
        typedef typename TFuncInfo1<TDeleter>::tParameter1 TResource;

        // 20.14.5.4.1 - unique_resource constructors
        unique_resource();
        unique_resource(TResource &&resource);
        unique_resource(TResource const &resource);

        // 20.14.5.4.2 - unique_resource destructor
        ~unique_resource();

        // 20.14.5.4.3 - unique_resource modifiers
        TResource release() throw();
        unique_resource_impl& reset(TResource&& resource);
        unique_resource_impl& reset(TResource const& resource);
        unique_resource_impl& invoke(bool bRelease = true);
        void operator()();
        void operator=(TResource &&resource);
        void operator=(TResource const &resource);

        // 20.14.5.4.4 - unique_resource accessors
        TResource get() const throw();
        operator TResource() const throw();
        TResource operator->() const;
        TResource* operator&();
        const TDeleter get_deleter() const;

        // 20.14.5.4.5 - unique_resource validity checking
        bool __inline valid() const throw();
    };

    //
    // 20.14.5.5 Helper Macros
    // The following macros simplify template parameters for unique_resource
    #define UNIQUE_DELETER(deleter_fn) decltype(&deleter_fn), deleter_fn, false
    #define UNIQUE_DELETER_THROW(deleter_fn) decltype(&deleter_fn), deleter_fn, true
    #define UNIQUE_DELETER_NOTHROW(deleter_fn) decltype(&deleter_fn), deleter_fn, false
}

20.14.5.1 The Reference Implementation - `unique_resource_impl`

unique_resource

20.14.5.2 Helper Classes

unique_resource

TFuncInfo

20.14.5.3 The Reference Implentation - `unique_resource`

unique_resource

unique_resource_impl

20.14.5.4 `unique_resource`

20.14.5.4.1 `unique_resource` construction

unique_resource

The type of the deleter function - a function taking a single parameter of the type of the resource being tracked. The resource type is deduced from the argument to the deleter function.
The deleter function itself. A static value that is known at compile time and can be expressed as a template parameter and invoked in the destructor by passing the tracked resource as the solitary parameter.
A bool value indicating whether or not the constructor or assignment operator should throw std::failed_resource_initialization if the resource is assigned (or constructed with) a value matching the no-delete or "invalid" value. The no-delete value must be of the type of the resource which is deduced from the argument required by the deleter function.
A no-delete or "invalid" value of the type of the resource being tracked. This parameter defaults to nullptr after having been cast (static_cast to the type of the resource.) The no-delete value must be a static value known at compile time that may be passed as a template parameter and used in a comparison withing the invoke() method or the destructor.

unique_resource

make_scoped_resource() is unsuitable or awkward, such as is the case for class member variables that can not be declared as auto.
Where very small (tight) code generation is desired, since the deleter function and no-delete value are static values that should not be stored in member variables.

unique_resource

//
// Most common usage - close "handle" types on scope-exit or class destruction...
extern HANDLE OpenFileW(const wchar_t *pwzFilename);
extern HANDLE CreateEventW(PSECURITY_ATTRIBUTES pEventAttributes, BOOL bManualReset, BOOL bInitialState, PCWSTR pName);
extern void SetEvent(HANDLE hEvent);
extern void CloseHandle(HANDLE h);
extern int open(const char *pszFilename, int oflags, ...);
extern void close(int iFileDesc);
extern ssize_t pwrite(int iFileDes, const void *pBuf, size_t szBytes, off_t offset);

class MyDataFile
{
private:
    const std::unique_resource<UNIQUE_DELETER(CloseHandle)> m_hWriteSignaledEvent;            // NOTE: Using helper macro
    std::unique_resource<decltype(&CloseHandle), CloseHandle, INVALID_HANDLE_VALUE> m_hFile;  // NOTE: Not using helper macro, also with non-default no-delete value
    std::unique_resource<UNIQUE_DELETER_NOTHROW(SetEvent)> hSignalThread;                     // NOTE: In this case we only want a .valid() event handle if it is created/assigned later - using default constructor
    std::vector<unsigned char> m_vData;
public:

    MyDataFile(const wchar_t *pwzFileName) :
        m_hWriteSignaledEvent(CreateEvent(nullptr, FALSE, FALSE, nullptr)),     // Note, very simple construction
        m_hFile(OpenFileW(pwzFileName))                                          // Notice that we let m_hSignalThread use the default constructor, it starts with .valid() == false
    {
    }
    .
    .
    .
    void SetEventToSignalOnClassDestruction(HANDLE hEvent)
    {
        m_hSignalThread = hEvent;           // Contrived example, but showing assignment operator after default construction...
        // When this class is destroyed, the event handle will be passed to SetEvent.  Also happens to an existing event handle prior to assignment of a new value.
    }

    DWORD WriteOnSignal()
    {
        DWORD dwWait = WaitForSingleObject(m_hWriteSignaledEvent, INFINITE);
        if(false == m_hFile.valid())        // Use validation method
        {
            return;
        }

        DWORD dwWritten = 0;
        if(WAIT_OBJECT_O == dwWait)
        {
            WriteFile(m_hFile, &m_vData, m_vData.size(), &dwWritten, nullptr);
        }
        return dwWritten;
    }
};

//
// Example using throw option...
void DumpVector(const char *pszFilename, std::vector<unsigned char> &vBuffer, off_t where)
{
    try
    {
        std::unique_resource<UNIQUE_DELETER_THROW(close, -1)> iFileDesc(open(pszFilename, O_RDWR|O_APPEND));
        if(pwrite(iFileDesc, &vBuffer[0], vBuffer.size(), where) != vBuffer.size())
        {
            throw write_failed;     // example, not defined here...
        }
    }
    catch (const std::failed_resource_initialization &e)
    {
        // Deal with error (file open failed) condition!
    }
}

20.14.5.4.2 unique_resource's destructor

unique_resource

release()

invoke(true)

20.14.5.4.3 unique_resource's modifiers

release() prevents the unique_resource from invoking the "deleter" function in the destructor, by assigning the no-delete value to the internally tracked resource. Returns a copy of the resource so that if needed it may be assigned to another tracking object, such as a unique_resource in another instance of a class (e.g. in a copy constructor).
reset(resource) causes the unique_resource to invoke the "deleter" function for any currently tracked and valid resource that has not been "released", and assigns a new resource to the unique_resource to be tracked. The unique_resource will be set to the "un-released" state when a new resource is assigned. The deleter function does not change. If the unique_resource was constructed with the throw-option, the new resource will be compared to the no-delete value passed to the constructor and std::failed_resource_initialization exception will be thrown if it matches.
invoke(true) performs an early (pre-destructor) invocation of the "deleter" function for a valid resource. The default true parameter sets the unique_resource to the "released" state so that the deleter function will not be invoked again when the destructor is called, unless the object is subsequently "reset."
invoke(false) performs an early (pre-destructor) invocation of the "deleter" function for a valid resource. The false parameter leaves the unique_resource in the "un-released" state so that the deleter function will be invoked again when the destructor is called.
operator()() performs an early (pre-destructor) invocation of the deleter function for a valid resource, the same as if invoke(true) had been called.
operator=(TResource &&res) performs an early (pre-destructor) invocation of the deleter function for a valid, assigned resource, and assigns a tracks a new resource the same as if reset(res) had been called.
operator=(TResource const &res) performs an early (pre-destructor) invocation of the deleter function for a valid, assigned resource, and assigns a tracks a new resource the same as if reset(res) had been called.

20.14.5.4.4 unique_resource accessors

TResource get() const throw() returns the resource being managed by the unique_resource object.
operator TResource() const throw() returns the resource being managed by the unique_resource object.
TResource operator->() const returns the resource being managed by the unique_resource object.
TResource* operator&() returns a pointer to the resource being managed by the unique_resource object, where the unique_resource has a private member of type TResource such as TResource m_resource; which is returned from this accessor with return &m_resource;
const TDeleter& get_deleter() const returns a reference to the deleter function. The deleter function can not be modified.

20.14.5.4.5 unique_resource validity checking

valid()

20.14.5.5 Helper Macros

unique_resource

UNIQUE_DELETER(delter_fn) - supplies the type of the deleter function, and the deleter function parameters, supplying false for the throw option.
UNIQUE_DELETER_THROW(delter_fn) - supplies the type of the deleter function, and the deleter function parameters, supplying true for the throw option.
UNIQUE_DELETER_NOTHROW(delter_fn) - supplies the type of the deleter function, and the deleter function parameters, supplying false for the throw option.

VII. Acknowledgements

Special thanks and recognition to those on both the Boost Developer mailing list and the ISO C++ std-proposal mailing list for advancing the design of the classes presented in this proposal and for general encouragement! Also, recognition is due to OpenSpan, Inc. for supporting the production of this proposal and for early adoption and testing of the reference implementation and prior implementations of the proposal in real world (and for that matter world class) products.

VIII. Reference Implemenation

reference implementation

http://www.andrewlsandoval.com/scope_exit/scoped_resource.h

IX. References

Boost.org, Boost Scope.Exit: Annex - Alternatives

Dr. Dobbs Magazine, Change the Way You Write Exception-Safe Code � Forever, Andrei Alexandrescu and Petru Marginean, December 01, 2000

A Proposal to Add additional RAII Wrappers to the Standard Library

I. Table of Contents

II. Introduction

III. Motivation and Scope

A. Motivation for scoped_function

Example scoped_function for mandatory logging on function exit:

Example scoped_function for loop advancement:

B. Motivation for scoped_resource_unchecked

scoped_resource_unchecked example:

C. Motivation for scoped_resource

Example using scoped_resource for with a C API:

Example using scoped_resource for with a Windows API:

D. Motivation for unique_resource

Example of unique_resource compared to a scoped_resource generated with make_scoped_resource()

Reference Implementation

Scope

Final Notes on Motivations and Scope:

IV. Impact on Standard

V. Design Decisions

A. General Principles

VI. Technical Specifications

Header

20.14 Scoped resources

20.14.1 Class template scoped_function

20.14.1.1 scoped_function constructors

20.14.1.2 scoped_function's destructor

20.14.1.3 scoped_function's modifiers

20.14.1.4 scoped_function's assignment operators

20.14.1.5 make_scoped_function

20.14.2 Class template scoped_resource_unchecked

20.14.2.1 scoped_resource_unchecked constructors

20.14.2.2 scoped_resource_unchecked's destructor

20.14.2.3 scoped_resource_unchecked's modifiers

20.14.2.4 scoped_resource_unchecked's accessors

20.14.2.5 make_scoped_resource_unchecked

20.14.2.6 make_scoped_resource

20.14.3 Addition of std::failed_resource_initialization exception

20.14.4 Class template scoped_resource

20.14.4.1 scoped_resource constructors

20.14.4.2 scoped_resource_unchecked's destructor

20.14.4.3 scoped_resource's modifiers

20.14.4.4 scoped_resource accessors

20.14.4.5 scoped_resource validity checking

20.14.4.6 make_scoped_resource - Default Generator Function

20.14.4.7 make_scoped_resource<true> - Generator Function which allows throws on allocation failure

20.14.5 Class template unique_resource

20.14.5.1 The Reference Implementation - unique_resource_impl

20.14.5.2 Helper Classes

20.14.5.3 The Reference Implentation - unique_resource

20.14.5.4 unique_resource

20.14.5.4.1 unique_resource construction

20.14.5.4.2 unique_resource's destructor

20.14.5.4.3 unique_resource's modifiers

20.14.5.4.4 unique_resource accessors

20.14.5.4.5 unique_resource validity checking

20.14.5.5 Helper Macros

VII. Acknowledgements

VIII. Reference Implemenation

IX. References

A. Motivation for `scoped_function`

Example `scoped_function` for mandatory logging on function exit:

Example `scoped_function` for loop advancement:

B. Motivation for `scoped_resource_unchecked`

`scoped_resource_unchecked` example:

C. Motivation for `scoped_resource`

Example using `scoped_resource` for with a C API:

Example using `scoped_resource` for with a Windows API:

D. Motivation for `unique_resource`

Example of `unique_resource` compared to a `scoped_resource` generated with `make_scoped_resource()`

20.14.1 Class template `scoped_function`

20.14.1.5 `make_scoped_function`

20.14.2 Class template `scoped_resource_unchecked`

20.14.2.5 `make_scoped_resource_unchecked`

20.14.2.6 `make_scoped_resource`

20.14.3 Addition of `std::failed_resource_initialization exception`

20.14.4 Class template `scoped_resource`

20.14.4.6 `make_scoped_resource - Default Generator Function`

20.14.4.7 `make_scoped_resource<true> - Generator Function which allows throws on allocation failure`

20.14.5 Class template `unique_resource`

20.14.5.1 The Reference Implementation - `unique_resource_impl`

20.14.5.3 The Reference Implentation - `unique_resource`

20.14.5.4 `unique_resource`

20.14.5.4.1 `unique_resource` construction