introduce unifex::async_resource

- async_destroy CPO
- returns a `unique_ptr`-like object

doc/api_reference.md

@@ -1194,6 +1194,20 @@ pass the state in as additional arguments.
 
 ## Other
 
+### `async_resource`
+
+Provides _async RAII_ programming idiom. `async_resource_ptr<T>` is like
+a `std::unique_ptr<T>` except that `async_resource_ptr<>`'s destructor destroys
+its `T` asynchronously, in constrast to `unique_ptr<>`'s destructor's
+synchronous invocation of `delete p_`. `async_resource` removes the need for
+manual lifetime management of a `Resource` protected by an `async_scope` and
+should be preferred over `async_scope`, if there is a need for one.
+
+1. explicitly supports parent / child relationship modeled as a tree
+2. allows for subtree removal / swap
+3. each `Resource` managed by `async_resource` has an associated, managed _inner_
+   `async_scope` without an explicit option to `join()`
+
 ### `async_scope`
 
 A place to safely spawn work such that it can be joined later.

include/unifex/async_destroy.hpp

@@ -0,0 +1,64 @@
+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * Licensed under the Apache License Version 2.0 with LLVM Exceptions
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *   https://llvm.org/LICENSE.txt
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#pragma once
+
+#include <unifex/just.hpp>
+#include <unifex/tag_invoke.hpp>
+
+#include <unifex/detail/prologue.hpp>
+
+namespace unifex {
+namespace _async_destroy {
+
+inline constexpr struct _destroy_fn {
+private:
+  template <typename Resource>
+  static auto try_invoke_member(Resource& resource, int) noexcept(
+      noexcept(resource.destroy())) -> decltype(resource.destroy()) {
+    return resource.destroy();
+  }
+
+  template <typename Resource>
+  [[deprecated(
+      "Can't async_destroy an object with no async_destroy customization; add "
+      "a no-op if that's what's intended.")]]  //
+  static auto
+  try_invoke_member(Resource&, double) noexcept {
+    return just();
+  }
+
+public:
+  template(typename Resource)                           //
+      (requires tag_invocable<_destroy_fn, Resource&>)  //
+      constexpr auto
+      operator()(Resource& resource) const
+      noexcept(is_nothrow_tag_invocable_v<_destroy_fn, Resource&>) {
+    return tag_invoke(_destroy_fn{}, resource);
+  }
+
+  template(typename Resource)                             //
+      (requires(!tag_invocable<_destroy_fn, Resource&>))  //
+      constexpr auto
+      operator()(Resource& resource) const
+      noexcept(noexcept(try_invoke_member(resource, 1))) {
+    return try_invoke_member(resource, 1);
+  }
+} async_destroy{};
+}  // namespace _async_destroy
+using _async_destroy::async_destroy;
+}  // namespace unifex
+
+#include <unifex/detail/epilogue.hpp>