feat: add unique_resource

Author: sjinks

.github/workflows/ci-vcpkg.yml

@@ -47,11 +47,6 @@ jobs:
       - name: Set up vcpkg
         uses: lukka/run-vcpkg@5e0cab206a5ea620130caf672fce3e4a6b5666a1 # v11.5
 
-      # - name: Fix for AppleClang
-      #   run: |
-      #     sudo xcode-select -s /Applications/Xcode_16.2.app/Contents/Developer
-      #   if: runner.os == 'macOS'
-
       - name: Build and test
         run: |
           cmake --preset debug-vcpkg -DBUILD_DOCS=OFF -DBUILD_EXAMPLES=OFF

README.md

@@ -6,11 +6,12 @@
 
 ## Overview
 
-This project provides a set of scope guard utilities for managing exit actions in C++. These utilities ensure that specified actions are executed when a scope is exited, regardless of how the exit occurs. The scope guards include:
+This project provides a set of utilities for managing exit actions and resource handling in C++. These utilities ensure that specified actions are executed when a scope is exited, regardless of (or depending on) how the exit occurs. The scope guards include:
 
 - `exit_action`: Executes an action when the scope is exited.
 - `fail_action`: Executes an action when the scope is exited due to an exception.
 - `success_action`: Executes an action when the scope is exited normally.
+- `unique_resource`: Manages a resource through a handle and disposes of that resource upon destruction (scope exit).
 
 These utilities are useful for ensuring that resources are properly released or actions are taken when a scope is exited.
 
@@ -19,11 +20,14 @@ These utilities are useful for ensuring that resources are properly released or
 - **exit_action**: Calls its exit function on destruction, when a scope is exited.
 - **fail_action**: Calls its exit function when a scope is exited via an exception.
 - **success_action**: Calls its exit function when a scope is exited normally.
+- **unique_resource**: Manages a resource with a custom deleter, ensuring the resource is released when the scope is exited.
 
 ## Usage
 
 ### Example Usage
 
+#### Scope Guards
+
 ```cpp
 #include <iostream>
 #include <scope_action.h>
@@ -77,6 +81,29 @@ int main()
 }
 ```
 
+#### `unique_resource`
+
+```cpp
+#include <cstdio>
+#include <unique_resource.h>
+
+int main()
+{
+    auto file = wwa::utils::make_unique_resource_checked(
+        std::fopen("potentially_nonexistent_file.txt", "r"), nullptr, std::fclose
+    );
+
+    if (file.get() != nullptr) {
+        std::puts("The file exists.\n");
+    }
+    else {
+        std::puts("The file does not exist.\n");
+    }
+
+    return 0;
+}
+```
+
 ## API Documentation
 
 The documentation is available at [https://sjinks.github.io/scope-action-cpp/](https://sjinks.github.io/scope-action-cpp/).
@@ -144,6 +171,50 @@ public:
 };
 ```
 
+### `unique_resource`
+
+A universal RAII resource handle wrapper for resource handles that owns and manages a resource through a handle and disposes of that resource upon destruction.
+
+```cpp
+template<typename Resource, typename Deleter>
+class [[nodiscard]] unique_resource {
+public:
+    unique_resource();
+
+    template<typename Res, typename Del>
+    unique_resource(Res&& r, Del&& d) noexcept(
+        (std::is_nothrow_constructible_v<WrappedResource, Res> || std::is_nothrow_constructible_v<WrappedResource, Res&>) &&
+        (std::is_nothrow_constructible_v<Deleter, Del> || std::is_nothrow_constructible_v<Deleter, Del&>)
+    );
+
+    unique_resource(unique_resource&& other) noexcept(std::is_nothrow_move_constructible_v<Resource> && std::is_nothrow_move_constructible_v<Deleter>);
+    ~unique_resource() noexcept;
+
+    unique_resource& operator=(unique_resource&& other) noexcept(
+        std::is_nothrow_move_assignable_v<Resource> && std::is_nothrow_move_assignable_v<Deleter>
+    )
+
+    void release() noexcept;
+    void reset() noexcept;
+
+    template<typename Res>
+    void reset(Res&& r);
+
+    const Resource& get() const noexcept;
+    const Deleter& get_deleter() const noexcept;
+
+    std::add_lvalue_reference_t<std::remove_pointer_t<Resource>> operator*() const noexcept;
+    Resource operator->() const noexcept
+};
+
+template<typename Resource, typename Deleter, typename Invalid = std::decay_t<Resource>>
+unique_resource<std::decay_t<Resource>, std::decay_t<Deleter>>
+make_unique_resource_checked(Resource&& r, const Invalid& invalid, Deleter&& d) noexcept(
+    std::is_nothrow_constructible_v<std::decay_t<Resource>, Resource> &&
+    std::is_nothrow_constructible_v<std::decay_t<Deleter>, Deleter>
+);
+```
+
 ## Building and Testing
 
 ### Prerequisites

examples/.clang-tidy

@@ -0,0 +1,4 @@
+---
+InheritParentConfig: true
+Checks: >
+  -cppcoreguidelines-owning-memory

examples/CMakeLists.txt

@@ -8,3 +8,6 @@ set_directory_properties(PROPERTIES INCLUDE_DIRECTORIES "${CMAKE_SOURCE_DIR}/src
 
 add_executable(scope_action scope_action.cpp)
 target_link_libraries(scope_action PRIVATE wwa::scope_action)
+
+add_executable(unique_resource unique_resource.cpp)
+target_link_libraries(unique_resource PRIVATE wwa::scope_action)

examples/unique_resource.cpp

@@ -0,0 +1,37 @@
+#include <cstdio>
+
+#ifndef _WIN32
+#    include <sys/socket.h>
+#    include <unistd.h>
+#endif
+
+#include "unique_resource.h"
+
+int main()
+{
+    //! [Using make_unique_resource_checked()]
+    auto file = wwa::utils::make_unique_resource_checked(
+        std::fopen("potentially_nonexistent_file.txt", "r"), nullptr, std::fclose
+    );
+
+    if (file.get() != nullptr) {
+        std::puts("The file exists.\n");
+    }
+    else {
+        std::puts("The file does not exist.\n");
+    }
+    //! [Using make_unique_resource_checked()]
+
+#ifndef _WIN32
+    //! [Using unique_resource]
+    int sock = socket(AF_INET, SOCK_STREAM, 0);
+    if (sock != -1) {
+        wwa::utils::unique_resource sock_guard(sock, close);
+        // Do something with the socket
+        // The socket will be closed when `sock_guard` goes out of scope
+    }
+    //! [Using unique_resource]
+#endif
+
+    return 0;
+}