Add distributed async docs

docs/sphinx/api/public_distributed_api.rst

@@ -177,3 +177,30 @@ Functions
    +---------------------------------------------------+
    | :cpp:func:`hpx::distributed::wait`                |
    +---------------------------------------------------+
+
+.. _public_distr_api_header_post:
+
+``hpx/async.hpp``
+===================
+
+The header :hpx-header:`libs/full/async_distributed/include,hpx/async.hpp`
+includes distributed implementations of :cpp:func:`hpx::async`,
+:cpp:func:`hpx::post`, :cpp:func:`hpx::sync`, and :cpp:func:`hpx::dataflow`.
+For information regarding the C++ standard library header, see :ref:`public_api`.
+
+Classes
+-------
+
+.. table:: Distributed implementation of classes of header ``hpx/async.hpp``
+
+   +---------------------------+
+   | Class                     |
+   +===========================+
+   | :cpp:class:`hpx::async`   |
+   +---------------------------+
+   | :cpp:func:`hpx::post`     |
+   +---------------------------+
+   | :cpp:func:`hpx::sync`     |
+   +---------------------------+
+   | :cpp:func:`hpx::dataflow` |
+   +---------------------------+

libs/full/async_distributed/include/hpx/async_distributed/async.hpp

@@ -4,8 +4,36 @@
 //  Distributed under the Boost Software License, Version 1.0. (See accompanying
 //  file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
+/// \file async.hpp
+/// \page hpx::async
+/// \headerfile hpx/async.hpp
+
 #pragma once
 
+#if defined(DOXYGEN)
+
+namespace hpx {
+    // clang-format off
+
+    /// \brief The distributed implementation of \c hpx::async can be used by
+    ///        giving an action instance as argument instead of a function,
+    ///        and also by providing another argument with the locality ID or
+    ///        the target ID. The action executes asynchronously.
+    ///
+    /// \tparam Action The type of action instance
+    /// \tparam Target The type of target where the action should be executed
+    /// \tparam Ts     The type of any additional arguments
+    ///
+    /// \param action  The action instance to be executed
+    /// \param target  The target where the action should be executed
+    /// \param ts      Additional arguments
+    ///
+    /// \returns \c hpx::future referring to the shared state created by this call to \c hpx::async
+    template <typename Action, typename Target, typename... Ts>
+    struct async(Action&& action, Target&& target, Ts&&... ts);
+    // clang-format on
+}   // namespace hpx
+
 #include <hpx/config.hpp>
 #include <hpx/actions_base/traits/extract_action.hpp>
 #include <hpx/actions_base/traits/is_client.hpp>
@@ -315,3 +343,5 @@ struct hpx::detail::async_dispatch<Bound,
         return bound.async(HPX_FORWARD(Us, vs)...);
     }
 };
+
+#endif

libs/full/async_distributed/include/hpx/async_distributed/dataflow.hpp

@@ -4,8 +4,39 @@
 //  Distributed under the Boost Software License, Version 1.0. (See accompanying
 //  file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
+/// \file dataflow.hpp
+/// \page hpx::dataflow
+/// \headerfile hpx/async.hpp
+
 #pragma once
 
+namespace hpx {
+    // clang-format off
+
+    /// \brief The distributed implementation of \c hpx::dataflow can be used by
+    ///        giving an action instance as argument instead of a function,
+    ///        and also by providing another argument with the locality ID or
+    ///        the target ID. The action executes asynchronously.
+    ///
+    /// \note Its behavior is similar to \c hpx::async with the exception that if
+    ///       one of the arguments is a future, then \c hpx::dataflow will wait
+    ///       for the future to be ready to launch the thread.
+    ///
+    /// \tparam Action The type of action instance
+    /// \tparam Target The type of target where the action should be executed
+    /// \tparam Ts     The type of any additional arguments
+    ///
+    /// \param action  The action instance to be executed
+    /// \param target  The target where the action should be executed
+    /// \param ts      Additional arguments
+    ///
+    /// \returns \c hpx::future referring to the shared state created by this call
+    ///          to \c hpx::dataflow
+    template <typename Action, typename Target, typename... Ts>
+    struct dataflow(Action&& action, Target&& target, Ts&&... ts);
+    // clang-format on
+}   // namespace hpx
+
 #include <hpx/config.hpp>
 #include <hpx/async_local/dataflow.hpp>
 #include <hpx/coroutines/detail/get_stack_pointer.hpp>
@@ -115,3 +146,5 @@ namespace hpx {
             HPX_FORWARD(F, f), Action{}, HPX_FORWARD(Ts, ts)...);
     }
 }    // namespace hpx
+
+#endif

libs/full/async_distributed/include/hpx/async_distributed/post.hpp

@@ -4,8 +4,37 @@
 //  Distributed under the Boost Software License, Version 1.0. (See accompanying
 //  file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
+/// \file post.hpp
+/// \page hpx::post
+/// \headerfile hpx/async.hpp
+
 #pragma once
 
+#if defined(DOXYGEN)
+
+namespace hpx {
+    // clang-format off
+
+    /// \brief The distributed implementation of \c hpx::post can be used by
+    ///        giving an action instance as argument instead of a function,
+    ///        and also by providing another argument with the locality ID or
+    ///        the target ID
+    ///
+    /// \tparam Action The type of action instance
+    /// \tparam Target The type of target where the action should be executed
+    /// \tparam Ts     The type of any additional arguments
+    ///
+    /// \param action  The action instance to be executed
+    /// \param target  The target where the action should be executed
+    /// \param ts      Additional arguments
+    ///
+    /// \returns \c true if the action was successfully posted,
+    ///          \c false otherwise.
+    template <typename Action, typename Target, typename... Ts>
+    bool post(Action&& action, Target&& target, Ts&&... ts);
+    // clang-format on
+}   // namespace hpx
+
 #include <hpx/config.hpp>
 #include <hpx/async_distributed/bind_action.hpp>
 #include <hpx/async_distributed/detail/post.hpp>
@@ -26,3 +55,5 @@ struct hpx::detail::post_dispatch<Bound,
         return bound.post(HPX_FORWARD(Us, vs)...);
     }
 };
+
+#endif

libs/full/async_distributed/include/hpx/async_distributed/sync.hpp

@@ -4,8 +4,36 @@
 //  Distributed under the Boost Software License, Version 1.0. (See accompanying
 //  file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
+/// \file sync.hpp
+/// \page hpx::sync
+/// \headerfile hpx/async.hpp
+
 #pragma once
 
+#if defined(DOXYGEN)
+
+namespace hpx {
+    // clang-format off
+
+    /// \brief The distributed implementation of \c hpx::sync can be used by
+    ///        giving an action instance as argument instead of a function,
+    ///        and also by providing another argument with the locality ID or
+    ///        the target ID. The action executes synchronously.
+    ///
+    /// \tparam Action The type of action instance
+    /// \tparam Target The type of target where the action should be executed
+    /// \tparam Ts     The type of any additional arguments
+    ///
+    /// \param action  The action instance to be executed
+    /// \param target  The target where the action should be executed
+    /// \param ts      Additional arguments
+    ///
+    /// \returns \c hpx::future referring to the shared state created by this call to \c hpx::sync
+    template <typename Action, typename Target, typename... Ts>
+    struct sync(Action&& action, Target&& target, Ts&&... ts);
+    // clang-format on
+}   // namespace hpx
+
 #include <hpx/config.hpp>
 #include <hpx/actions_base/traits/extract_action.hpp>
 #include <hpx/actions_base/traits/is_client.hpp>
@@ -246,3 +274,5 @@ namespace hpx::detail {
         }
     };
 }    // namespace hpx::detail
+
+#endif