From 7f33a2b12764c7d668aa24070a99a4718749825a Mon Sep 17 00:00:00 2001 From: dimitraka Date: Sun, 14 Apr 2024 15:46:27 +0200 Subject: [PATCH] Add distributed async docs --- cmake/templates/conf.py.in | 5 ++- docs/sphinx/api/public_distributed_api.rst | 28 ++++++++++++++ .../include/hpx/async_distributed/async.hpp | 32 ++++++++++++++++ .../hpx/async_distributed/dataflow.hpp | 37 +++++++++++++++++++ .../include/hpx/async_distributed/post.hpp | 33 +++++++++++++++++ .../include/hpx/async_distributed/sync.hpp | 32 ++++++++++++++++ 6 files changed, 165 insertions(+), 2 deletions(-) diff --git a/cmake/templates/conf.py.in b/cmake/templates/conf.py.in index abe721ce0c10..5378d4986f91 100644 --- a/cmake/templates/conf.py.in +++ b/cmake/templates/conf.py.in @@ -744,15 +744,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 diff --git a/docs/sphinx/api/public_distributed_api.rst b/docs/sphinx/api/public_distributed_api.rst index bc5cbe322a73..338a2cb74a8a 100644 --- a/docs/sphinx/api/public_distributed_api.rst +++ b/docs/sphinx/api/public_distributed_api.rst @@ -177,3 +177,31 @@ 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`. + +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` | + +-------------------------------------------------------+ + diff --git a/libs/full/async_distributed/include/hpx/async_distributed/async.hpp b/libs/full/async_distributed/include/hpx/async_distributed/async.hpp index c9b84dfe34e7..c43bef1ebc9b 100644 --- a/libs/full/async_distributed/include/hpx/async_distributed/async.hpp +++ b/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 + HPX_FORCEINLINE auto async(Action&& action, Target&& target, Ts&&... ts); + // clang-format on +} // namespace hpx + +#else + #include #include #include @@ -315,3 +345,5 @@ struct hpx::detail::async_dispatch + decltype(auto) dataflow(Action&& action, Target&& target, Ts&&... ts); + // clang-format on +} // namespace hpx + +#else + #include #include #include @@ -115,3 +150,5 @@ namespace hpx { HPX_FORWARD(F, f), Action{}, HPX_FORWARD(Ts, ts)...); } } // namespace hpx + +#endif diff --git a/libs/full/async_distributed/include/hpx/async_distributed/post.hpp b/libs/full/async_distributed/include/hpx/async_distributed/post.hpp index 491faf6f3f45..9fa3019f3dea 100644 --- a/libs/full/async_distributed/include/hpx/async_distributed/post.hpp +++ b/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 + bool post(Action&& action, Target&& target, Ts&&... ts); + // clang-format on +} // namespace hpx + +#else + #include #include #include @@ -26,3 +57,5 @@ struct hpx::detail::post_dispatch + decltype(auto) sync(Action&& action, Target&& target, Ts&&... ts); + // clang-format on +} // namespace hpx + +#else + #include #include #include @@ -246,3 +276,5 @@ namespace hpx::detail { } }; } // namespace hpx::detail + +#endif