Add documentation for distributed implementations of post, async, sync and dataflow

cmake/templates/conf.py.in

@@ -777,15 +777,16 @@ html_context = {
     'github_version': 'master/docs/sphinx/',
 }
 
+# In case no commit is found, link to the master
 if "@HPX_WITH_GIT_COMMIT_SHORT@" != "":
     html_context['commit'] = "@HPX_WITH_GIT_COMMIT_SHORT@"
 else:
-    html_context['commit'] = "unknown"
+    html_context['commit'] = "master"
 
 if "@HPX_WITH_GIT_COMMIT@" != "":
     html_context['fullcommit'] = "@HPX_WITH_GIT_COMMIT@"
 else:
-    html_context['fullcommit'] = "unknown"
+    html_context['fullcommit'] = "master"
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

docs/sphinx/api/public_distributed_api.rst

@@ -177,3 +177,30 @@ Member functions
    +----------------------------------------------------------+
    | :cpp:func:`hpx::distributed::latch::wait`                |
    +----------------------------------------------------------+
+
+.. _public_distr_api_header_async:
+
+``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`.
+
+Functions
+---------
+
+.. table:: Distributed implementation of functions of header ``hpx/async.hpp``
+
+   +-------------------------------------------------------+
+   | Functions                                             |
+   +=======================================================+
+   | :ref:`modules_hpx/async_distributed/async.hpp_api`    |
+   +-------------------------------------------------------+
+   | :ref:`modules_hpx/async_distributed/sync.hpp_api`     |
+   +-------------------------------------------------------+
+   | :ref:`modules_hpx/async_distributed/post.hpp_api`     |
+   +-------------------------------------------------------+
+   | :ref:`modules_hpx/async_distributed/dataflow.hpp_api` |
+   +-------------------------------------------------------+

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

@@ -4,8 +4,38 @@
 //  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 (distributed)
+/// \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>
+    HPX_FORCEINLINE auto async(Action&& action, Target&& target, Ts&&... ts);
+    // clang-format on
+}    // namespace hpx
+
+#else
+
 #include <hpx/config.hpp>
 #include <hpx/actions_base/traits/extract_action.hpp>
 #include <hpx/actions_base/traits/is_client.hpp>
@@ -315,3 +345,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,43 @@
 //  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 (distributed)
+/// \headerfile hpx/async.hpp
+
 #pragma once
 
+#if defined(DOXYGEN)
+
+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>
+    decltype(auto) dataflow(Action&& action, Target&& target, Ts&&... ts);
+    // clang-format on
+}    // namespace hpx
+
+#else
+
 #include <hpx/config.hpp>
 #include <hpx/async_local/dataflow.hpp>
 #include <hpx/coroutines/detail/get_stack_pointer.hpp>
@@ -115,3 +150,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,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 post.hpp
+/// \page hpx::post (distributed)
+/// \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
+
+#else
+
 #include <hpx/config.hpp>
 #include <hpx/async_distributed/bind_action.hpp>
 #include <hpx/async_distributed/detail/post.hpp>
@@ -26,3 +57,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,38 @@
 //  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 (distributed)
+/// \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>
+    decltype(auto) sync(Action&& action, Target&& target, Ts&&... ts);
+    // clang-format on
+}    // namespace hpx
+
+#else
+
 #include <hpx/config.hpp>
 #include <hpx/actions_base/traits/extract_action.hpp>
 #include <hpx/actions_base/traits/is_client.hpp>
@@ -246,3 +276,5 @@ namespace hpx::detail {
         }
     };
 }    // namespace hpx::detail
+
+#endif