unique_resource.qbk

[/
 / Copyright 2023-2024 Andrey Semashev
 /
 / Distributed under the Boost Software License, Version 1.0.
 / (See accompanying file LICENSE_1_0.txt or copy at
 / https://www.boost.org/LICENSE_1_0.txt)
 /
 / This document is a part of Boost.Scope library documentation.
 /]

[section:unique_resource Unique resource wrapper]

    #include <``[boost_scope_unique_resource_hpp]``>

Boost.Scope provides a [class_scope_unique_resource] class template. This is a wrapper for an arbitrary resource that represents exclusive
ownership of the resource. The wrapper offers access to the owned resource and automatically calls a deleter function object to free the
resource upon destruction. This is a generalization of `std::unique_ptr`, but while `std::unique_ptr` is only used to wrap pointers,
[class_scope_unique_resource] can wrap other types of resources as well.

A resource type must have the following properties to be compatible with [class_scope_unique_resource]:

* Move-constructible, where the move constructor is marked as `noexcept`, or
* Copy-constructible, or
* An lvalue reference to an object type.

Note that if the resource type is a reference, the referenced object must be stored externally to the [class_scope_unique_resource] wrapper
and must remain valid for the entire duration of ownership by the wrapper. Users are not expected to access the resource object other than
through the [class_scope_unique_resource] wrapper. For example, it is not allowed to modify the resource object by setting it to an invalid
state or explicitly freeing the resource circumventing the resource wrapper, as the wrapper will still invoke the deleter on the then-invalid
resource.

The deleter must be a function object type that is callable on an lvalue of the resource type. The deleter must be copy-constructible.
Although not strictly required, it is generally highly recommended that calling a deleter on a resource doesn't throw exceptions and is marked
`noexcept`, as the deleter will often be called from the [class_scope_unique_resource] destructor.

Like `std::unique_ptr`, [class_scope_unique_resource] is not copyable and supports a number of other operations, such as move construction and
assignment, `reset`, `release` and `swap` with the similar semantics. Some of the operations impose additional requirements on the resource and
deleter types; such operations will not be available if those requirements aren't met. For example, `swap` is only supported if both
the resource and deleter types are swappable, and at least one of those types is nothrow swappable (the last part is necessary to implement the
[@https://en.cppreference.com/w/cpp/language/exceptions strong exception guarantee] for the `swap` operation). The requirements are listed for
each operation in the [class_scope_unique_resource] class reference.

[tip If the resource type is dereferenceable (i.e. supports unary `operator*`), [class_scope_unique_resource] also provides `operator*` and
`operator->`, making it act more like a smart-pointer.]

Let's consider a usage example. Here, we need to compare the contents of two files; `equal_files` returns `true` if the files have equal
contents and `false` otherwise.

    // A deleter for POSIX-like file descriptors
    struct fd_deleter
    {
        void operator() (int fd) const noexcept
        {
            if (fd >= 0)
                close(fd);
        }
    };

    // Opens a file with the given filename for reading and returns wrapped file descriptor
    boost::scope::unique_resource< int, fd_deleter > open_file(std::string const& filename)
    {
        boost::scope::unique_resource< int, fd_deleter > file(open(filename.c_str(), O_RDONLY));
        if (file.get() < 0)
        {
            int err = errno;
            throw std::system_error(err, std::generic_category(), "Failed to open file " + filename);
        }

        return file;
    }

    // Reads contents of a file denoted by fd into buffer and returns the number of read bytes
    std::size_t read_file(int fd, unsigned char* buf, std::size_t size)
    {
        std::size_t total_read_size = 0;
        while (total_read_size < size)
        {
            ssize_t read_size = read(fd, buf + total_read_size, size - total_read_size);
            if (read_size < 0)
            {
                int err = errno;
                if (err == EINTR)
                    continue;
                throw std::system_error(err, std::generic_category(), "Failed to write data");
            }

            if (read_size == 0)
            {
                // End of file
                break;
            }

            total_read_size += read_size;
        }

        return total_read_size;
    }

    // Compares contents of two files for equality
    bool equal_files(std::string const& filename1, std::string const& filename2)
    {
        // Create unique resource wrappers for files
        auto file1 = open_file(filename1.c_str());
        auto file2 = open_file(filename2.c_str());

        // Use them to read file contents
        constexpr std::size_t buf_size = 1024;
        unsigned char buf1[buf_size];
        unsigned char buf2[buf_size];
        while (true)
        {
            std::size_t size1 = read_file(file1.get(), buf1, buf_size);
            std::size_t size2 = read_file(file2.get(), buf2, buf_size);

            if (size1 != size2)
            {
                // File sizes are different
                return false;
            }

            if (std::memcmp(buf1, buf2, size1) != 0)
            {
                // File contents are different
                return false;
            }

            if (size1 < buf_size)
            {
                // Files have ended. At this point we know they have equal contents.
                break;
            }
        }

        return true;
    }

[note POSIX-like file descriptors are supported on Windows through non-standard APIs like
[@https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/open-wopen `_open`],
[@https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/close `_close`],
[@https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/read `_read`],
[@https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/write `_write`] and others. It is often possible to port a program
performing simple IO with regular files and file descriptors to Windows by simple renaming. However, here and below we will be using
the standard POSIX nomenclature.]

In this example, there are several points to note. First, the `fd_deleter` function object checks if the file descriptor is valid before
passing it to `close`. This is necessary in this piece of code because we unconditionally initialize [class_scope_unique_resource] object
with the value returned by `open`, which may be -1 indicating an error. By default, [class_scope_unique_resource] doesn't discriminate
valid (i.e. allocated) resource values from invalid (i.e. unallocated), which means that from its perspective the value of -1 is a file
descriptor that needs to be freed by calling the deleter on it. Therefore, the deleter must be prepared to handle resource values that are
unallocated. Later on we will see how to mitigate this.

[tip Besides the resource value, you can specify the deleter object as the second argument of the [class_scope_unique_resource] constructor.
In fact, the second argument is mandatory if the deleter is not default-constructible or if its default constructor may throw. This is
necessary to be able to call the deleter on the passed resource value, should the construction of either the resource or the deleter throw.
This ensures that the resource doesn't leak in case if [class_scope_unique_resource] initialization fails.]

Second, we still need to check if opening the file succeeded before using it. Since [class_scope_unique_resource] in this example is always
constructed in allocated state, we have to check the file descriptor value for being negative. In order to access the resource value one
can use the `get` method of [class_scope_unique_resource].

We can improve this example by making [class_scope_unique_resource] initialization automatically check for the file descriptor validity.
This will only require modifying `fd_deleter` and `open_file`, the rest of the code stays unchanged.

    // A deleter for POSIX-like file descriptors
    struct fd_deleter
    {
        void operator() (int fd) const noexcept
        {
            close(fd);
        }
    };

    // Opens a file with the given filename for reading and returns wrapped file descriptor
    boost::scope::unique_resource< int, fd_deleter > open_file(std::string const& filename)
    {
        auto file = boost::scope::make_unique_resource_checked(
            open(filename.c_str(), O_RDONLY)
            -1,
            fd_deleter());
        if (!file.allocated())
        {
            int err = errno;
            throw std::system_error(err, std::generic_category(), "Failed to open file " + filename);
        }

        return file;
    }

Here, the `make_unique_resource_checked` helper function performs the following:

# If the resource value, which is the first argument - the result of the `open` call, is equal to the invalid resource value, which is
  the second argument, creates and returns an unallocated [class_scope_unique_resource] object.
# Otherwise, creates and returns an allocated [class_scope_unique_resource] object that wraps the result of the `open` call.
# In both cases, the third argument is used to initialize the deleter in the returned [class_scope_unique_resource] object.

Note that if `open` fails and returns -1, the deleter is guaranteed not to be called on this resource value - neither by
`make_unique_resource_checked` nor by [class_scope_unique_resource], not even if [class_scope_unique_resource] construction fails with an
exception. This allows us to simplify `fd_deleter` and remove the check for negative `fd` values.

[tip If C++17 is supported, it is possible to use __boost_core_functor__ from __boost_core__ to wrap raw functions like `close` into
a function object that can be specified as a deleter in `unique_resource`. For example, `fd_deleter` from the example above could be
replaced with `boost::core::functor< close >`.]

Furthermore, since the returned [class_scope_unique_resource] object now properly indicates whether the resource is allocated or not,
we can use the `allocated` member function to test it instead of checking the resource value. This makes the code more readable.

[note In order to avoid confusion with the [class_scope_unique_resource] object being always allocated after construction with a resource
value, it is recommended to always use either the `make_unique_resource_checked` factory function or, more preferably, resource traits,
as described in the next section. Resource traits are the preferred solution as it makes [class_scope_unique_resource] more efficient and
less error-prone to use.]

[section:resource_traits Resource traits]

The [class_scope_unique_resource] class template also supports an optional third template parameter, which can be used to specify a resource
traits class. Resource traits provide [class_scope_unique_resource] with additional knowledge about the resource features that allow for
a more efficient implementation. This is useful when there is one or more resource value that is considered unallocated, that is such a value
that does not identify an allocated resource that needs to be freed. For example, for pointer resource types, null is usually considered as
the unallocated value, and for POSIX-like file descriptors, all negative values are unallocated values, since no valid file descriptor
can be negative.

If `Resource` is the resource type specified in [class_scope_unique_resource] template parameters then, if specified, resource traits must
be a class type with the following public static member functions:

* `bool is_allocated(Resource const& r) noexcept` - must return `true` if the resource value `r` is an allocated resource value and `false`
  otherwise.
* `R make_default() noexcept` - must return a value such that `std::is_constructible< Resource, R >::value && std::is_nothrow_assignable<
  Resource&, R >::value` is `true` and constructing `Resource` from `R` produces an unallocated resource value that can be used to initialize
  the default-constructed [class_scope_unique_resource] object.

Note that all listed member functions must be non-throwing. Given these definitions, calling `is_allocated` on the value returned by
`make_default` must always return `false`.

When the conforming resource traits are provided, [class_scope_unique_resource] behavior changes as follows:

* [class_scope_unique_resource] will no longer separately track whether it is in allocated state or not and instead will use `is_allocated`
  on the wrapped resource value for this. In particular, this means that constructing [class_scope_unique_resource] from a resource value
  or calling `reset` with a resource value may now produce a wrapper in an unallocated state, if the resource value is an unallocated value.
* Default constructor, `reset` with no arguments, move constructor and move assignment of [class_scope_unique_resource] will use `make_default`
  to initialize the resource value in the unallocated wrapper (for move operations - in the move source).

Using the resource traits allow us to further improve the example given in the previous section. Again, our primary interest is `open_file`
and `unique_resource` type usage, the rest of `equal_files` implementation remains unchanged.

    // A deleter for POSIX-like file descriptors
    struct fd_deleter
    {
        void operator() (int fd) const noexcept
        {
            close(fd);
        }
    };

    // Resource traits for POSIX-like file descriptors
    struct fd_resource_traits
    {
        static bool is_allocated(int fd) noexcept
        {
            return fd >= 0;
        }

        static int make_default() noexcept
        {
            // Return any unallocated resource value
            return -1;
        }
    };

    // A shorthand type alias for unique file descriptor wrappers
    using unique_fd = boost::scope::unique_resource< int, fd_deleter, fd_resource_traits >;

    // Opens a file with the given filename for reading and returns wrapped file descriptor
    unique_fd open_file(std::string const& filename)
    {
        unique_fd file(open(filename.c_str(), O_RDONLY));
        if (!file.allocated())
        {
            int err = errno;
            throw std::system_error(err, std::generic_category(), "Failed to open file " + filename);
        }

        return file;
    }

In this piece of code, we no longer need to use `make_unique_resource_checked` every time we open a file (or otherwise create a file
descriptor), and therefore we don't have to duplicate the invalid file descriptor value or the deleter - this information is provided
by `fd_resource_traits` and conveniently embedded in the `unique_fd` type. As before, if `open` fails and returns -1, the constructed
[class_scope_unique_resource] object will be in an unallocated state, meaning that we can use `allocated` accessor, and that the deleter
will only be called if `open` succeeded.

[tip The `fd_deleter`, `fd_resource_traits` and `unique_fd` types presented in the examples above are provided by the library out of
the box in [boost_scope_fd_resource_hpp] and [boost_scope_unique_fd_hpp] headers.]

[endsect]

[section:simplified_resource_traits Simplified resource traits]

[note Components described in this section require a C++17 compiler that supports [@https://en.cppreference.com/w/cpp/language/template_parameters
`auto` non-type template parameters] and [@https://en.cppreference.com/w/cpp/language/fold fold expressions].]

The library provides an `unallocated_resource` class template that can be used to generate resource traits for use with `unique_resource`
when the resource satisfies the following constraints:

* Resource values are allowed to be specified as [@https://en.cppreference.com/w/cpp/language/template_parameters non-type template parameters]
  in C++. The exact set of types that meet this requirement depends on the C++ standard version being used. For example, integers,
  enumerations, pointers and lvalue references are supported since C++17. C++20 adds support for class types. Note that resource value
  initialization expression must be a constant expression. In particular, for pointers and references this means that the resource value
  initialization expression must refer to an object or function or, in case of pointers, produce a null pointer.
* There is one or more unallocated resource values that can be individually listed. All other resource values represent allocated resources
  that need to be freed.
* One of these unallocated resource values is considered the default.
* Resource type supports move construction and assignment from the default value, as well as comparison for equality and inequality with
  unallocated values, and none of these operations throw exceptions.

When the above requirements are met, one can specify the unallocated resource values as non-type template parameters of `unallocated_resource` to
generate resource traits for `unique_resource`. The first of the listed unallocated values is the default.

For example, let's consider resource traits definition for Windows [@https://learn.microsoft.com/en-us/windows/win32/sysinfo/handles-and-objects
handles].

    struct handle_traits
    {
        //! Returns the default resource value
        static HANDLE make_default() noexcept
        {
            return INVALID_HANDLE_VALUE;
        }

        //! Tests if \a res is an allocated resource value
        static bool is_allocated(HANDLE res) noexcept
        {
            return res != INVALID_HANDLE_VALUE && res != (HANDLE)NULL;
        }
    };

Here, `INVALID_HANDLE_VALUE` is a special constant returned by some Windows API functions that indicates no allocated resource associated with
the handle. However, other functions, like [@https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-openprocess
`OpenProcess`] or [@https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-openthread `OpenThread`] for example,
return a `NULL` handle in case of errors, and we have to test for that value as well.

[tip For the curious readers, there is an [@https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443 article] describing reasons for this
inconsistency between different Windows APIs.]

With `unallocated_resource`, the above resource traits could be reduced to this:

    using handle_traits = boost::scope::unallocated_resource< INVALID_HANDLE_VALUE, (HANDLE)NULL >;

[note Given that `INVALID_HANDLE_VALUE` is defined as `(HANDLE)-1` in Windows SDK, and `HANDLE` is actually a pointer type, in pure C++
one should not be able to specify this value as a non-type template parameter because the pointer does not refer to an object. However, MSVC
accepts this code as an extension. With other compilers, one would still have to implement proper resource traits similar to `handle_traits`
in this case.]

We can also use __boost_core_functor__ to wrap the [@https://learn.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-closehandle
`CloseHandle`] Windows API function, which is used to free handles, to define the resource deleter. Then the complete definition of
`unique_resource` would look like this:

    using unique_handle = boost::scope::unique_resource<
        HANDLE,
        boost::core::functor< CloseHandle >,
        boost::scope::unallocated_resource< INVALID_HANDLE_VALUE, (HANDLE)NULL >
    >;

[endsect]

[section:comparison_with_library_fundamentals_ts Comparison with `unique_resource` defined in C++ Extensions for Library Fundamentals]

The following sections provide comparison between `unique_resource` defined by [@https://cplusplus.github.io/fundamentals-ts/v3.html#scopeguard.uniqueres
C++ Extensions for Library Fundamentals TS] and this library.

[section:resource_traits Resource traits]

Boost.Scope supports an additional optional template parameter for [link scope.unique_resource.resource_traits resource traits]. This allows
`unique_resource` to become aware of the resource specifics, such as unallocated values and the default value, which is useful for usability and
efficiency. Specifying resource traits makes the `make_unique_resource_checked` factory function unnecessary, as `unique_resource` itself is
able to tell whether the resource is allocated upon construction. Additionally, this allows `unique_resource` to avoid storing an additional
flag that indicates whether the resource is is in an allocated state and needs to be freed upon destruction.

Using resource traits may change meaning of some `unique_resource` APIs, which is, arguably, for the better. Consider the following example.

    // POSIX file descriptor resource
    std::experimental::unique_resource< int, int (*)(int) > fd(-1, &close);

Since the deleter in this case must be specified in constructor parameters (because the default constructor would create a value-initialized
pointer to function, which is null and cannot be called), the user may be inclined to specify -1 for the file descriptor and expect that the
constructed `unique_resource` is in an unallocated state. This assumption would be incorrect because this constructor always creates an
allocated `unique_resource`, which means it will call `close(-1)` upon destruction. The correct way to construct `fd` in this case would be
to use `make_unique_resource_checked` like so:

    std::experimental::unique_resource< int, int (*)(int) > fd = std::experimental::make_unique_resource_checked(-1, -1, &close);

Alternatively, one can call `release` immediately after constructing the `unique_resource`. Although it should be noted that this approach
is only valid if it is known that `unique_resource` construction cannot throw.

    std::experimental::unique_resource< int, int (*)(int) > fd(-1, &close);
    fd.release(); // mark the resource unallocated

A similar problem exists with the `reset` member function.

    fd.reset(-1);

Contrary to expectation, this call does not leave `fd` in unallocated state and also causes `close(-1)` to be called on `fd` destruction. The
correct way to do this is to call `reset` without parameters or use `make_unique_resource_checked`.

    fd.reset();
    // or:
    fd = std::experimental::make_unique_resource_checked(-1, -1, &close);

[note It may look like calling `reset(-1)` is an artificial example that doesn't happen in practice. It is not unusual for one to want to
combine another call with `reset` directly (e.g. `fd.reset(open(...))`) and expect this to work correctly. However, since `open` may return -1
in case of error, we will have the problem described above.]

Specifying resource traits changes meaning of the above examples. Both the constructor and `reset` from an unallocated resource value produce
a `unique_resource` object in an unallocated state.

    boost::scope::unique_resource< int, int (*)(int), boost::scope::fd_resource_traits > fd(-1, &close);
    assert(!fd.allocated());

    fd.reset(-1);
    assert(!fd.allocated());

[tip [class_scope_fd_resource_traits] is provided by Boost.Scope.]

Another benefit of resource traits is that the default resource value can be different from the value-constructed one. This can be useful if
the resource type is not default-constructible (for example, if it is a reference type) or the value-constructed resource is not an unallocated
value. For example, [class_scope_fd_resource_traits] specifies -1 as the default value for POSIX file descriptors because the value of 0 is a
valid allocated file descriptor.

There is no direct replacement for this feature the Library Fundamentals TS, although `make_unique_resource_checked` and `release` can be used
to work around the limitation in some cases, as shown above.

[endsect]

[section:constructors Constructor differences]

Unlike Library Fundamentals TS, Boost.Scope does not consider pointers to functions default-constructible for the purpose of deleters specified
in `unique_resource` template parameters. For example:

    std::experimental::unique_resource< int, int (*)(int) > fd1; // compiles, creates unusable unique_resource object
    boost::scope::unique_resource< int, int (*)(int) > fd2; // fails to compile, unique_resource is not default-constructible

This is because the default- or value-constructed pointer to function is not callable, as it is garbage or null pointer, respectively.
`unique_resource` does not provide a way to modify the deleter after construction, other than by move-assigning another `unique_resource` object,
which means the default-constructed `unique_resource` object would be unusable and potentially cause undefined behavior on `reset` or destruction.

Boost.Scope does allow omitting the deleter from constructor arguments when it truly is default-constructible and the default constructor doesn't
throw exceptions, while the TS requires both the resource value and the deleter to be specified.

    std::experimental::unique_resource< int, boost::scope::fd_deleter > fd1(10); // fails to compile, deleter is missing in constructor arguments
    boost::scope::unique_resource< int, boost::scope::fd_deleter > fd2(10); // ok, default-constructs fd_deleter

[tip [class_scope_fd_deleter] is provided by Boost.Scope.]

[note The requirement for the deleter default construction to be non-throwing is to ensure that the deleter can be invoked on the resource in
case if `unique_resource` construction fails with an exception. This prevents leaking the resource if its construction throws, or the deleter's
constructor throws.]

Boost.Scope allows omitting the resource value in `unique_resource` constructor arguments, when the deleter must be specified. `default_resource`
keyword can be used as a placeholder for the resource value in this case:

    // Creates an unallocated unique_resource with the specified deleter
    boost::scope::unique_resource< int, int (*)(int) > fd(boost::scope::default_resource, &close);

Note that in the example above, even though the resource value is value-initialized (i.e. zero), the `fd` is in an unallocated state and will not
call the deleter on destruction. `default_resource` also works with resource traits:

    boost::scope::unique_resource< int, int (*)(int), boost::scope::fd_resource_traits > fd(boost::scope::default_resource, &close);

In the above case, the `fd` object will use the default value specified by the resource traits (i.e. -1, in case of fd_resource_traits) to initialize
its stored resource object. Again, the `fd` object is in an unallocated state after construction.

Library Fundamentals TS specifies that `unique_resource` move constructor must deallocate the resource if the resource is nothrow move-constructible
and the deleter is not and the deleter's copy constructor throws and exception. This is a case when `unique_resource` is half-constructed: the
resource has been moved into the object being constructed (i.e. is no longer stored in the source object) but the deleter fails to copy-construct
(i.e. it only exists in the source object). The behavior described in the TS ensures that the resource doesn't leak, but it leaves the source
`unique_resource` unallocated in case of exception, which means the move constructor only maintains
[@https://en.cppreference.com/w/cpp/language/exceptions#Exception_safety basic exception guarantee]. Boost.Scope in this case leaves the source
`unique_resource` in its original state, which also guarantees that the resource doesn't leak, but provides a strong exception guarantee.

[endsect]

[section:check_allocated Checking whether resource is allocated]

One glaring omission in the Library Fundamentals TS is that `unique_resource` doesn't provide a way to test whether the resource is in an allocated
state. Boost.Scope rectifies this by providing `allocated()` method, as well as contextual conversion to `bool`.

    boost::scope::unique_resource< int, int (*)(int), boost::scope::fd_resource_traits > fd(-1, &close);
    assert(!fd.allocated());
    assert(!fd);

    fd.reset(10);
    assert(fd.allocated());
    assert(!!fd);

[note The contextual conversion to `bool` in `unique_resource` does not test the resource /value/ and only tests whether the resource is allocated.
This is consistent with other components, such as `std::optional`, for example.]

[endsect]

[section:swap Native support for swapping]

Library Fundamentals TS defines `unique_resource` to be a move-constructible and move-assignable type, and through this property it supports the
standard `std::swap` algorithm. However, there are two issues with this approach:

* It prevents swapping algorithms specialized for the resource and deleter types from being used. Even if `swap` is specialized, the generic
  algorithm involving moving or copying the resource and deleter objects is used.
* The generic `swap` implementation only provides [@https://en.cppreference.com/w/cpp/language/exceptions#Exception_safety basic exception guarantee].
  The algorithm move-constructs a copy of one of the source objects and then performs two move-assignments. If either of the assignments fail, one
  of the `unique_resource` objects will be left unallocated. It is also worth noting that the TS defines `unique_resource` move constructor to be
  potentially destructive. If the resource type move constructor is non-throwing and the deleter copy-constructor throws, the deleter is called on
  the move-constructed resource object to avoid leaking it. In the context of `std::swap` this means that even if the move constructor fails, it will
  leave the source object unallocated rather than unmodified.

Boost.Scope provides native support for swapping, both as a member and non-member function `swap`. Swapping is supported if at least one of the
resource or deleter types support non-throwing swap (either default or specialized algorithm) and provides strong exception guarantee.
`unique_resource` swap operation is non-throwing if both resource and deleter types support non-throwing swap.

    boost::scope::unique_resource< int, boost::scope::fd_deleter, boost::scope::fd_resource_traits > fd1, fd2;
    fd1.swap(fd2);
    swap(fd1, fd2); // found via ADL

[endsect]

[section:dereference Broader support for dereferencing]

Library Fundamentals TS `unique_resource` supports `operator*()` and `operator->()` for pointer resource types. Boost.Scope extends this support
for any resource types that support dereferencing.

    // Resource object type
    struct my_object
    {
        void foo();
    };

    // Manager for my_object instances
    class my_object_manager
    {
    private:
        // List of allocated objects
        using my_object_list = std::list< my_object >;

        // Resource handle that refers to a my_object element in the list
        class my_handle
        {
        private:
            my_object_list* m_list;
            my_object_list::iterator m_it;

        public:
            my_handle() noexcept : m_list(nullptr), m_it() {}
            explicit my_handle(my_object_list& list, my_object_list::iterator it) noexcept :
                m_list(&list), m_it(it)
            {
            }

            my_object_list::iterator operator-> () const noexcept  /*< The operator relies on `operator->` chaining. >*/
            {
                return m_it;
            }

            my_object& operator* () const noexcept
            {
                return *m_it;
            }

            my_object_list* get_list() const noexcept
            {
                return m_list;
            }

            my_object_list::iterator get_iterator() const noexcept
            {
                return m_it;
            }
        };

        // Resource deleter
        struct my_handle_deleter
        {
            void operator() (my_handle const& res) const noexcept
            {
                res.get_list()->erase(res.get_iterator());
            }
        };

        // Resource traits
        struct my_handle_traits
        {
            static my_handle make_default() noexcept
            {
                return my_handle();
            }

            static bool is_allocated(my_handle const& res) noexcept
            {
                return res.get_list() != nullptr && res.get_iterator() != res.get_list()->end();
            }
        };

    public:
        // Unique resource wrapper for my_object instances
        using my_object_handle = boost::scope::unique_resource< my_handle, my_handle_deleter, my_handle_traits >;

    private:
        my_object_list m_objects;

    public:
        // Allocates a new object and returns a handle to it
        my_object_handle allocate_object()
        {
            return my_object_handle(my_handle(m_objects, m_objects.insert(m_objects.end(), my_object())));
        }
    };

    void allocate_and_use_object(my_object_manager& mgr)
    {
        my_object_manager::my_object_handle handle = mgr.allocate_object();
        if (handle)
            handle->foo(); // invokes my_object::foo on the allocated object
    }

In the above example, we're using `unique_resource` to reference objects created and maintained by `my_object_manager`. The `my_handle` class
is the resource type and supports accessing `my_object` members through `operator->` and `operator*`. This enables `operator->` and `operator*`
in `unique_resource`, which allows the code that uses `unique_resource` to access `my_object` members.

With Library Fundamentals TS `unique_resource`, this is possible to emulate by accessing the stored resource object via the `unique_resource::get`
accessor and dereferencing that.

[endsect]

[endsect]

[endsect]