From 1d51d606ae3ee1ac667a1e44ddc1dcb097aa4052 Mon Sep 17 00:00:00 2001 From: dimitraka Date: Wed, 20 Sep 2023 19:17:06 +0200 Subject: [PATCH 1/7] Add distributed API documentation --- docs/sphinx/api.rst | 5 ++ docs/sphinx/api/public_distributed_api.rst | 95 ++++++++++++++++++++++ 2 files changed, 100 insertions(+) create mode 100644 docs/sphinx/api/public_distributed_api.rst diff --git a/docs/sphinx/api.rst b/docs/sphinx/api.rst index b38ec175b78e..9ca821d85671 100644 --- a/docs/sphinx/api.rst +++ b/docs/sphinx/api.rst @@ -59,6 +59,11 @@ a heading brings in the features listed under that heading. api/public_api.rst +.. toctree:: + :maxdepth: 1 + + api/public_distributed_api.rst + .. toctree:: :maxdepth: 1 diff --git a/docs/sphinx/api/public_distributed_api.rst b/docs/sphinx/api/public_distributed_api.rst new file mode 100644 index 000000000000..28867af8af24 --- /dev/null +++ b/docs/sphinx/api/public_distributed_api.rst @@ -0,0 +1,95 @@ +.. + Copyright (C) 2023 Dimitra Karatza + + SPDX-License-Identifier: BSL-1.0 + 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) + +.. _public_distributed_api: + +====================== +Public distributed API +====================== + +Our Public Distributed API offers a rich set of tools and functions that enable developers +to harness the full potential of distributed computing. Here, you'll find a comprehensive +list of header files, classes and functions for various distributed computing features +provided by |hpx|. + +.. _public_distr_api_header_all_gather: + +``hpx/collectives/all_gather.hpp`` +================================== + +The header :hpx-header:`libs/full/collectives/include,hpx/collectives/all_gather.hpp` +contains definitions and implementations related to the `all_gather` operation. + +Functions +--------- + +.. table:: `hpx` functions of header ``hpx/collectives/all_gather.hpp`` + + +------------------------------------------+ + | Function | + +==========================================+ + | :cpp:func:`hpx::collectives::all_gather` | + +------------------------------------------+ + +.. _public_distr_api_header_all_reduce: + +``hpx/collectives/all_reduce.hpp`` +================================== + +The header :hpx-header:`libs/full/collectives/include,hpx/collectives/all_reduce.hpp` +contains definitions and implementations related to the `all_reduce` operation. + +Functions +--------- + +.. table:: `hpx` functions of header ``hpx/collectives/all_reduce.hpp`` + + +------------------------------------------+ + | Function | + +==========================================+ + | :cpp:func:`hpx::collectives::all_reduce` | + +------------------------------------------+ + +.. _public_distr_api_header_all_to_all: + +``hpx/collectives/all_to_all.hpp`` +================================== + +The header :hpx-header:`libs/full/collectives/include,hpx/collectives/all_to_all.hpp` +contains definitions and implementations related to the `all_to_all` operation. + +Functions +--------- + +.. table:: `hpx` functions of header ``hpx/collectives/all_to_all.hpp`` + + +------------------------------------------+ + | Function | + +==========================================+ + | :cpp:func:`hpx::collectives::all_to_all` | + +------------------------------------------+ + +.. _public_distr_api_header_argument_types: + +``hpx/collectives/argument_types.hpp`` +================================== + +The header :hpx-header:`libs/full/collectives/include,hpx/collectives/argument_types.hpp` +contains definitions and implementations related to the `argument_types` operation. + +Functions +--------- + +.. table:: `hpx` functions of header ``hpx/collectives/argument_types.hpp`` + + +----------------------------------------------+ + | Function | + +==============================================+ + | :cpp:class:`hpx::collectives::argument_type` | + +----------------------------------------------+ + | :cpp:func:`hpx::collectives::argument_type` | + +----------------------------------------------+ From 6460725dc80e6e27d5d9c70e746c3b5fb1fd1aa3 Mon Sep 17 00:00:00 2001 From: dimitraka Date: Sun, 1 Oct 2023 21:49:05 +0200 Subject: [PATCH 2/7] Create header file to include collectives --- libs/full/include/include/hpx/collectives.hpp | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 libs/full/include/include/hpx/collectives.hpp diff --git a/libs/full/include/include/hpx/collectives.hpp b/libs/full/include/include/hpx/collectives.hpp new file mode 100644 index 000000000000..4d560ba8f083 --- /dev/null +++ b/libs/full/include/include/hpx/collectives.hpp @@ -0,0 +1,27 @@ +// Copyright (c) 2023 Dimitra Karatza +// +// SPDX-License-Identifier: BSL-1.0 +// 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) + +#pragma once + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include From cd5fbe7fb1c342a2e91b7f0d68ea1253d21d8981 Mon Sep 17 00:00:00 2001 From: dimitraka Date: Sun, 1 Oct 2023 21:49:53 +0200 Subject: [PATCH 3/7] List collectives in a table --- docs/sphinx/api/public_distributed_api.rst | 125 ++++++++---------- libs/full/include/include/hpx/collectives.hpp | 6 - 2 files changed, 58 insertions(+), 73 deletions(-) diff --git a/docs/sphinx/api/public_distributed_api.rst b/docs/sphinx/api/public_distributed_api.rst index 28867af8af24..2f9db939576c 100644 --- a/docs/sphinx/api/public_distributed_api.rst +++ b/docs/sphinx/api/public_distributed_api.rst @@ -16,80 +16,71 @@ to harness the full potential of distributed computing. Here, you'll find a comp list of header files, classes and functions for various distributed computing features provided by |hpx|. -.. _public_distr_api_header_all_gather: +.. _public_distr_api_header_collectives: -``hpx/collectives/all_gather.hpp`` -================================== +``hpx/collectives.hpp`` +======================= -The header :hpx-header:`libs/full/collectives/include,hpx/collectives/all_gather.hpp` -contains definitions and implementations related to the `all_gather` operation. +The header :hpx-header:`libs/full/include/include,hpx/collectives.hpp` +contains definitions and implementations related to the collectives operations. -Functions ---------- - -.. table:: `hpx` functions of header ``hpx/collectives/all_gather.hpp`` - - +------------------------------------------+ - | Function | - +==========================================+ - | :cpp:func:`hpx::collectives::all_gather` | - +------------------------------------------+ - -.. _public_distr_api_header_all_reduce: - -``hpx/collectives/all_reduce.hpp`` -================================== - -The header :hpx-header:`libs/full/collectives/include,hpx/collectives/all_reduce.hpp` -contains definitions and implementations related to the `all_reduce` operation. - -Functions ---------- - -.. table:: `hpx` functions of header ``hpx/collectives/all_reduce.hpp`` - - +------------------------------------------+ - | Function | - +==========================================+ - | :cpp:func:`hpx::collectives::all_reduce` | - +------------------------------------------+ - -.. _public_distr_api_header_all_to_all: - -``hpx/collectives/all_to_all.hpp`` -================================== - -The header :hpx-header:`libs/full/collectives/include,hpx/collectives/all_to_all.hpp` -contains definitions and implementations related to the `all_to_all` operation. - -Functions ---------- - -.. table:: `hpx` functions of header ``hpx/collectives/all_to_all.hpp`` - - +------------------------------------------+ - | Function | - +==========================================+ - | :cpp:func:`hpx::collectives::all_to_all` | - +------------------------------------------+ - -.. _public_distr_api_header_argument_types: +Classes +------- -``hpx/collectives/argument_types.hpp`` -================================== +.. table:: `hpx` classes of header ``hpx/collectives.hpp`` -The header :hpx-header:`libs/full/collectives/include,hpx/collectives/argument_types.hpp` -contains definitions and implementations related to the `argument_types` operation. + +-----------------------------------------------------+ + | Function | + +=====================================================+ + | :cpp:class:`hpx::collectives::barrier` | + +-----------------------------------------------------+ + | :cpp:class:`hpx::collectives::channel_communicator` | + +-----------------------------------------------------+ Functions --------- -.. table:: `hpx` functions of header ``hpx/collectives/argument_types.hpp`` +.. table:: `hpx` functions of header ``hpx/collectives.hpp`` + + +-----------------------------------------------------------+ + | Function | + +===========================================================+ + | :cpp:func:`hpx::collectives::all_gather` | + +-----------------------------------------------------------+ + | :cpp:func:`hpx::collectives::all_reduce` | + +-----------------------------------------------------------+ + | :cpp:func:`hpx::collectives::all_to_all` | + +-----------------------------------------------------------+ + | :cpp:func:`hpx::collectives::broadcast_to` | + +-----------------------------------------------------------+ + | :cpp:func:`hpx::collectives::broadcast_from` | + +-----------------------------------------------------------+ + | :cpp:func:`hpx::collectives::create_channel_communicator` | + +-----------------------------------------------------------+ + | :cpp:func:`hpx::collectives::set` | + +-----------------------------------------------------------+ + | :cpp:func:`hpx::collectives::get` | + +-----------------------------------------------------------+ + | :cpp:func:`hpx::collectives::create_communication_set` | + +-----------------------------------------------------------+ + | :cpp:func:`hpx::collectives::create_communicator` | + +-----------------------------------------------------------+ + | :cpp:func:`hpx::collectives::create_local_communicator` | + +-----------------------------------------------------------+ + | :cpp:func:`hpx::collectives::exclusive_scan` | + +-----------------------------------------------------------+ + | :cpp:func:`hpx::collectives::gather_here` | + +-----------------------------------------------------------+ + | :cpp:func:`hpx::collectives::gather_there` | + +-----------------------------------------------------------+ + | :cpp:func:`hpx::collectives::inclusive_scan` | + +-----------------------------------------------------------+ + | :cpp:func:`hpx::collectives::reduce_here` | + +-----------------------------------------------------------+ + | :cpp:func:`hpx::collectives::reduce_there` | + +-----------------------------------------------------------+ + | :cpp:func:`hpx::collectives::scatter_from` | + +-----------------------------------------------------------+ + | :cpp:func:`hpx::collectives::scatter_to` | + +-----------------------------------------------------------+ - +----------------------------------------------+ - | Function | - +==============================================+ - | :cpp:class:`hpx::collectives::argument_type` | - +----------------------------------------------+ - | :cpp:func:`hpx::collectives::argument_type` | - +----------------------------------------------+ diff --git a/libs/full/include/include/hpx/collectives.hpp b/libs/full/include/include/hpx/collectives.hpp index 4d560ba8f083..11517fad9a1f 100644 --- a/libs/full/include/include/hpx/collectives.hpp +++ b/libs/full/include/include/hpx/collectives.hpp @@ -10,18 +10,12 @@ #include #include #include -#include #include -#include #include #include #include #include -#include #include #include -#include #include -#include #include -#include From 14bfa4c4d8f2bd57bededc29553284512c0c8d16 Mon Sep 17 00:00:00 2001 From: dimitraka Date: Tue, 10 Oct 2023 19:14:13 +0200 Subject: [PATCH 4/7] Fix typo --- docs/sphinx/api/public_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/api/public_api.rst b/docs/sphinx/api/public_api.rst index 4138a0bf1bb3..adda00d9da84 100644 --- a/docs/sphinx/api/public_api.rst +++ b/docs/sphinx/api/public_api.rst @@ -524,7 +524,7 @@ Classes :cpp:class:`hpx::promise`, but will eventually refer to :cpp:class:`hpx::promise` after a deprecation period. -.. table:: Distributed implementation of classes of header ``hpx/latch.hpp`` +.. table:: Distributed implementation of classes of header ``hpx/future.hpp`` +---------------------------------------+ | Class | From 236a3d424c6d35db4113fe5fb0043295c58531d1 Mon Sep 17 00:00:00 2001 From: dimitraka Date: Tue, 10 Oct 2023 19:48:10 +0200 Subject: [PATCH 5/7] Add distributed public API for collectives, latch, barrier --- docs/sphinx/api/public_distributed_api.rst | 99 +++++++++++++++++++++- 1 file changed, 97 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/api/public_distributed_api.rst b/docs/sphinx/api/public_distributed_api.rst index 2f9db939576c..f614189ca927 100644 --- a/docs/sphinx/api/public_distributed_api.rst +++ b/docs/sphinx/api/public_distributed_api.rst @@ -16,6 +16,39 @@ to harness the full potential of distributed computing. Here, you'll find a comp list of header files, classes and functions for various distributed computing features provided by |hpx|. +.. _public_distr_api_header_barrier: + +``hpx/barrier.hpp`` +=================== + +The header :hpx-header:`libs/full/include/include,hpx/barrier.hpp` includes +a distributed barrier implementation. For information regarding the C++ standard +library header :cppreference-header:`barrier`, see :ref:`public_api`. + +Classes +------- + +.. table:: Distributed implementation of classes of header ``hpx/barrier.hpp`` + + +----------------------------------------+ + | Class | + +========================================+ + | :cpp:class:`hpx::distributed::barrier` | + +----------------------------------------+ + +Functions +--------- + +.. table:: `hpx` functions of header ``hpx/barrier.hpp`` + + +-------------------------------------------+ + | Function | + +===========================================+ + | :cpp:func:`hpx::distributed::wait` | + +-------------------------------------------+ + | :cpp:func:`hpx::distributed::synchronize` | + +-------------------------------------------+ + .. _public_distr_api_header_collectives: ``hpx/collectives.hpp`` @@ -30,12 +63,28 @@ Classes .. table:: `hpx` classes of header ``hpx/collectives.hpp`` +-----------------------------------------------------+ - | Function | + | Class | +=====================================================+ - | :cpp:class:`hpx::collectives::barrier` | + | :cpp:struct:`hpx::collectives::num_sites_arg` | + +-----------------------------------------------------+ + | :cpp:struct:`hpx::collectives::this_site_arg` | + +-----------------------------------------------------+ + | :cpp:struct:`hpx::collectives::that_site_arg` | + +-----------------------------------------------------+ + | :cpp:struct:`hpx::collectives::generation_arg` | + +-----------------------------------------------------+ + | :cpp:struct:`hpx::collectives::root_site_arg` | + +-----------------------------------------------------+ + | :cpp:struct:`hpx::collectives::tag_arg` | + +-----------------------------------------------------+ + | :cpp:struct:`hpx::collectives::arity_arg` | + +-----------------------------------------------------+ + | :cpp:class:`hpx::collectives::communicator` | +-----------------------------------------------------+ | :cpp:class:`hpx::collectives::channel_communicator` | +-----------------------------------------------------+ + | :cpp:class:`hpx::collectives::communicator` | + +-----------------------------------------------------+ Functions --------- @@ -67,6 +116,12 @@ Functions +-----------------------------------------------------------+ | :cpp:func:`hpx::collectives::create_local_communicator` | +-----------------------------------------------------------+ + | :cpp:func:`hpx::collectives::set_info` | + +-----------------------------------------------------------+ + | :cpp:func:`hpx::collectives::get_info` | + +-----------------------------------------------------------+ + | :cpp:func:`hpx::collectives::is_root` | + +-----------------------------------------------------------+ | :cpp:func:`hpx::collectives::exclusive_scan` | +-----------------------------------------------------------+ | :cpp:func:`hpx::collectives::gather_here` | @@ -84,3 +139,43 @@ Functions | :cpp:func:`hpx::collectives::scatter_to` | +-----------------------------------------------------------+ +.. _public_distr_api_header_latch: + +``hpx/latch.hpp`` +================= + +The header :hpx-header:`libs/full/include/include,hpx/latch.hpp` includes +a distributed latch implementation. For information regarding the C++ standard +library header :cppreference-header:`latch`, see :ref:`public_api`. + +Classes +------- + +.. table:: Distributed implementation of classes of header ``hpx/latch.hpp`` + + +--------------------------------------+ + | Class | + +======================================+ + | :cpp:class:`hpx::distributed::latch` | + +--------------------------------------+ + +Functions +--------- + +.. table:: `hpx` functions of header ``hpx/latch.hpp`` + + +---------------------------------------------------+ + | Function | + +===================================================+ + | :cpp:func:`hpx::distributed::count_down_and_wait` | + +---------------------------------------------------+ + | :cpp:func:`hpx::distributed::arrive_and_wait` | + +---------------------------------------------------+ + | :cpp:func:`hpx::distributed::count_down` | + +---------------------------------------------------+ + | :cpp:func:`hpx::distributed::is_ready` | + +---------------------------------------------------+ + | :cpp:func:`hpx::distributed::try_wait` | + +---------------------------------------------------+ + | :cpp:func:`hpx::distributed::wait` | + +---------------------------------------------------+ From a35e58fb4a199b25c4b604e9516d7dda87d4bd42 Mon Sep 17 00:00:00 2001 From: dimitraka Date: Fri, 13 Oct 2023 20:37:30 +0200 Subject: [PATCH 6/7] Add doxygen docs --- .../include/hpx/collectives/argument_types.hpp | 18 ++++++++++++++++++ .../hpx/collectives/channel_communicator.hpp | 2 ++ .../hpx/collectives/create_communicator.hpp | 2 ++ 3 files changed, 22 insertions(+) diff --git a/libs/full/collectives/include/hpx/collectives/argument_types.hpp b/libs/full/collectives/include/hpx/collectives/argument_types.hpp index 9b87dd07bec7..cdc0db51e01a 100644 --- a/libs/full/collectives/include/hpx/collectives/argument_types.hpp +++ b/libs/full/collectives/include/hpx/collectives/argument_types.hpp @@ -50,11 +50,29 @@ namespace hpx::collectives { struct arity_tag; } // namespace detail + /// The number of participating sites (default: all localities) using num_sites_arg = detail::argument_type; + + /// The local end of the communication channel using this_site_arg = detail::argument_type; + + /// The opposite end of the communication channel using that_site_arg = detail::argument_type; + + /// The generational counter identifying the sequence number of the + /// operation performed on the given base name. It needs to be supplied + /// only if the operation on the given base name has to be performed + /// more than once. It must be a positive number greater than zero. using generation_arg = detail::argument_type; + + /// The site that is responsible for creating the support object + /// of the operation. It defaults to '0' (zero). using root_site_arg = detail::argument_type; + + /// The tag identifying the concrete operation using tag_arg = detail::argument_type; + + /// The number of children each of the communication nodes is connected + /// to (default: picked based on num_sites). using arity_arg = detail::argument_type; } // namespace hpx::collectives diff --git a/libs/full/collectives/include/hpx/collectives/channel_communicator.hpp b/libs/full/collectives/include/hpx/collectives/channel_communicator.hpp index 63fcbe5b834c..0fb7180605b7 100644 --- a/libs/full/collectives/include/hpx/collectives/channel_communicator.hpp +++ b/libs/full/collectives/include/hpx/collectives/channel_communicator.hpp @@ -117,6 +117,8 @@ namespace hpx { namespace collectives { /////////////////////////////////////////////////////////////////////////// // forward declarations + /// a handle identifying the communication channel to use for get/set + /// operations class channel_communicator; template diff --git a/libs/full/collectives/include/hpx/collectives/create_communicator.hpp b/libs/full/collectives/include/hpx/collectives/create_communicator.hpp index d39f682edbde..652cc4534612 100644 --- a/libs/full/collectives/include/hpx/collectives/create_communicator.hpp +++ b/libs/full/collectives/include/hpx/collectives/create_communicator.hpp @@ -140,6 +140,8 @@ struct hpx::util::extra_data_helper namespace hpx::collectives { /////////////////////////////////////////////////////////////////////////// + /// a handle identifying the communication channel to use for a particular + /// collective operation struct communicator : hpx::components::client_base From 0fe7d3850c8feffe91cf12b2ebf8bd0726a83524 Mon Sep 17 00:00:00 2001 From: dimitraka Date: Tue, 17 Oct 2023 23:46:49 +0200 Subject: [PATCH 7/7] Add documentation --- docs/sphinx/api/public_distributed_api.rst | 12 +- libs/full/collectives/CMakeLists.txt | 16 +- .../include/hpx/collectives/barrier.hpp | 148 ++++++++++-------- .../hpx/collectives/channel_communicator.hpp | 18 +-- .../hpx/collectives/communication_set.hpp | 13 +- .../hpx/collectives/create_communicator.hpp | 6 +- .../include/hpx/collectives/latch.hpp | 101 +++++++++++- libs/full/include/CMakeLists.txt | 1 + 8 files changed, 213 insertions(+), 102 deletions(-) diff --git a/docs/sphinx/api/public_distributed_api.rst b/docs/sphinx/api/public_distributed_api.rst index f614189ca927..bc5cbe322a73 100644 --- a/docs/sphinx/api/public_distributed_api.rst +++ b/docs/sphinx/api/public_distributed_api.rst @@ -63,7 +63,7 @@ Classes .. table:: `hpx` classes of header ``hpx/collectives.hpp`` +-----------------------------------------------------+ - | Class | + | Class | +=====================================================+ | :cpp:struct:`hpx::collectives::num_sites_arg` | +-----------------------------------------------------+ @@ -79,12 +79,10 @@ Classes +-----------------------------------------------------+ | :cpp:struct:`hpx::collectives::arity_arg` | +-----------------------------------------------------+ - | :cpp:class:`hpx::collectives::communicator` | + | :cpp:struct:`hpx::collectives::communicator` | +-----------------------------------------------------+ | :cpp:class:`hpx::collectives::channel_communicator` | +-----------------------------------------------------+ - | :cpp:class:`hpx::collectives::communicator` | - +-----------------------------------------------------+ Functions --------- @@ -116,11 +114,11 @@ Functions +-----------------------------------------------------------+ | :cpp:func:`hpx::collectives::create_local_communicator` | +-----------------------------------------------------------+ - | :cpp:func:`hpx::collectives::set_info` | + | :cpp:func:`hpx::collectives::communicator::set_info` | +-----------------------------------------------------------+ - | :cpp:func:`hpx::collectives::get_info` | + | :cpp:func:`hpx::collectives::communicator::get_info` | +-----------------------------------------------------------+ - | :cpp:func:`hpx::collectives::is_root` | + | :cpp:func:`hpx::collectives::communicator::is_root` | +-----------------------------------------------------------+ | :cpp:func:`hpx::collectives::exclusive_scan` | +-----------------------------------------------------------+ diff --git a/libs/full/collectives/CMakeLists.txt b/libs/full/collectives/CMakeLists.txt index 7a39d66c272a..b2a95b67c932 100644 --- a/libs/full/collectives/CMakeLists.txt +++ b/libs/full/collectives/CMakeLists.txt @@ -41,15 +41,15 @@ set(collectives_headers # Default location is $HPX_ROOT/libs/collectives/include_compatibility # cmake-format: off set(collectives_compat_headers - hpx/collectives.hpp => hpx/include/lcos.hpp - hpx/lcos/barrier.hpp => hpx/barrier.hpp - hpx/lcos/broadcast.hpp => hpx/include/lcos.hpp - hpx/lcos/fold.hpp => hpx/include/lcos.hpp - hpx/lcos/gather.hpp => hpx/include/lcos.hpp - hpx/lcos/latch.hpp => hpx/latch.hpp - hpx/lcos/reduce.hpp => hpx/include/lcos.hpp - hpx/lcos/spmd_block.hpp => hpx/include/lcos.hpp + hpx/lcos/barrier.hpp => hpx/barrier.hpp + hpx/lcos/broadcast.hpp => hpx/include/lcos.hpp + hpx/lcos/fold.hpp => hpx/include/lcos.hpp + hpx/lcos/gather.hpp => hpx/include/lcos.hpp + hpx/lcos/latch.hpp => hpx/latch.hpp + hpx/lcos/reduce.hpp => hpx/include/lcos.hpp + hpx/lcos/spmd_block.hpp => hpx/include/lcos.hpp ) + # cmake-format: on # Default location is $HPX_ROOT/libs/collectives/src diff --git a/libs/full/collectives/include/hpx/collectives/barrier.hpp b/libs/full/collectives/include/hpx/collectives/barrier.hpp index 564c0644719e..e846f61a7651 100644 --- a/libs/full/collectives/include/hpx/collectives/barrier.hpp +++ b/libs/full/collectives/include/hpx/collectives/barrier.hpp @@ -8,6 +8,85 @@ #pragma once +#if defined(DOXYGEN) +// clang-format off +namespace hpx { namespace distributed { + + /// The barrier is an implementation performing a barrier over a number of + /// participating threads. The different threads don't have to be on the + /// same locality. This barrier can be invoked in a distributed application. + /// + /// For a local only barrier \see hpx::barrier. + class HPX_EXPORT barrier; + + /// Creates a barrier, rank is locality id, size is number of localities + /// + /// \param base_name The name of the barrier + /// + /// A barrier \a base_name is created. It expects that + /// hpx::get_num_localities() participate and the local rank is + /// hpx::get_locality_id(). + explicit barrier(std::string const& base_name); + + /// Creates a barrier with a given size, rank is locality id + /// + /// \param base_name The name of the barrier + /// \param num The number of participating threads + /// + /// A barrier \a base_name is created. It expects that + /// \a num participate and the local rank is hpx::get_locality_id(). + barrier(std::string const& base_name, std::size_t num); + + /// Creates a barrier with a given size and rank + /// + /// \param base_name The name of the barrier + /// \param num The number of participating threads + /// \param rank The rank of the calling site for this invocation + /// + /// A barrier \a base_name is created. It expects that + /// \a num participate and the local rank is \a rank. + barrier( + std::string const& base_name, std::size_t num, std::size_t rank); + + /// Creates a barrier with a vector of ranks + /// + /// \param base_name The name of the barrier + /// \param ranks Gives a list of participating ranks (this could be derived + /// from a list of locality ids + /// \param rank The rank of the calling site for this invocation + /// + /// A barrier \a base_name is created. It expects that ranks.size() + /// and the local rank is \a rank (must be contained in \a ranks). + barrier(std::string const& base_name, + std::vector const& ranks, std::size_t rank); + + /// Wait until each participant entered the barrier. Must be called by + /// all participants + /// + /// \returns This function returns once all participants have entered + /// the barrier (have called \a wait). + void wait() const; + + /// Wait until each participant entered the barrier. Must be called by + /// all participants + /// + /// \returns a future that becomes ready once all participants have + /// entered the barrier (have called \a wait). + hpx::future wait(hpx::launch::async_policy) const; + + /// Perform a global synchronization using the default global barrier + /// The barrier is created once at startup and can be reused throughout + /// the lifetime of an HPX application. + /// + /// \note This function currently does not support dynamic connection + /// and disconnection of localities. + static void synchronize(); + +}} // namespace hpx::distributed + +// clang-format on +#else + #include #include #include @@ -24,90 +103,36 @@ namespace hpx::distributed { - /// \cond NOINTERNAL namespace detail { struct barrier_node; } - /// \endcond - /// The barrier is an implementation performing a barrier over a number of - /// participating threads. The different threads don't have to be on the - /// same locality. This barrier can be invoked in a distributed application. - /// - /// For a local only barrier \see hpx::barrier. class HPX_EXPORT barrier { - /// \cond NOINTERNAL typedef detail::barrier_node wrapped_type; typedef components::managed_component wrapping_type; - /// \endcond public: - /// Creates a barrier, rank is locality id, size is number of localities - /// - /// \param base_name The name of the barrier - /// - /// A barrier \a base_name is created. It expects that - /// hpx::get_num_localities() participate and the local rank is - /// hpx::get_locality_id(). explicit barrier(std::string const& base_name); - /// Creates a barrier with a given size, rank is locality id - /// - /// \param base_name The name of the barrier - /// \param num The number of participating threads - /// - /// A barrier \a base_name is created. It expects that - /// \a num participate and the local rank is hpx::get_locality_id(). barrier(std::string const& base_name, std::size_t num); - /// Creates a barrier with a given size and rank - /// - /// \param base_name The name of the barrier - /// \param num The number of participating threads - /// \param rank The rank of the calling site for this invocation - /// - /// A barrier \a base_name is created. It expects that - /// \a num participate and the local rank is \a rank. barrier( std::string const& base_name, std::size_t num, std::size_t rank); - /// Creates a barrier with a vector of ranks - /// - /// \param base_name The name of the barrier - /// \param ranks Gives a list of participating ranks (this could be derived - /// from a list of locality ids - /// \param rank The rank of the calling site for this invocation - /// - /// A barrier \a base_name is created. It expects that ranks.size() - /// and the local rank is \a rank (must be contained in \a ranks). barrier(std::string const& base_name, std::vector const& ranks, std::size_t rank); - /// \cond NOINTERNAL barrier(barrier&& other) noexcept; barrier& operator=(barrier&& other) noexcept; - /// \cond NOINTERNAL ~barrier(); - /// \endcond - /// Wait until each participant entered the barrier. Must be called by - /// all participants - /// - /// \returns This function returns once all participants have entered - /// the barrier (have called \a wait). void wait() const; - /// Wait until each participant entered the barrier. Must be called by - /// all participants - /// - /// \returns a future that becomes ready once all participants have - /// entered the barrier (have called \a wait). hpx::future wait(hpx::launch::async_policy) const; - /// \cond NOINTERNAL // Resets this barrier instance. void release(); @@ -116,32 +141,23 @@ namespace hpx::distributed { // Get the instance of the global barrier static std::array& get_global_barrier(); static std::array create_global_barrier(); - /// \endcond - - /// Perform a global synchronization using the default global barrier - /// The barrier is created once at startup and can be reused throughout - /// the lifetime of an HPX application. - /// - /// \note This function currently does not support dynamic connection - /// and disconnection of localities. + static void synchronize(); private: - /// \cond NOINTERNAL barrier(); hpx::intrusive_ptr node_; - /// \endcond }; } // namespace hpx::distributed -/// \cond NOINTERNAL namespace hpx::lcos { using barrier HPX_DEPRECATED_V(1, 8, "hpx::lcos::barrier is deprecated, use hpx::distributed::barrier " "instead") = hpx::distributed::barrier; } -/// \endcond #include + +#endif // DOXYGEN diff --git a/libs/full/collectives/include/hpx/collectives/channel_communicator.hpp b/libs/full/collectives/include/hpx/collectives/channel_communicator.hpp index 0fb7180605b7..ca011d3d17ef 100644 --- a/libs/full/collectives/include/hpx/collectives/channel_communicator.hpp +++ b/libs/full/collectives/include/hpx/collectives/channel_communicator.hpp @@ -11,8 +11,14 @@ #include #if defined(DOXYGEN) -// clang-format off + +/// Top level HPX namespace namespace hpx { namespace collectives { + // clang-format off + + /// A handle identifying the communication channel to use for get/set + /// operations + class channel_communicator{}; /// Create a new communicator object usable with peer-to-peer /// channel-based operations @@ -91,9 +97,8 @@ namespace hpx { namespace collectives { template hpx::future get(channel_communicator comm, that_site_arg site, tag_arg tag = tag_arg()); - -}} -// clang-format on + // clang-format on +}} // namespace hpx::collectives #else @@ -112,13 +117,9 @@ namespace hpx { namespace collectives { #include #include -/////////////////////////////////////////////////////////////////////////////// namespace hpx { namespace collectives { - /////////////////////////////////////////////////////////////////////////// // forward declarations - /// a handle identifying the communication channel to use for get/set - /// operations class channel_communicator; template @@ -129,7 +130,6 @@ namespace hpx { namespace collectives { hpx::future set( channel_communicator, that_site_arg, T&&, tag_arg = tag_arg()); - /////////////////////////////////////////////////////////////////////////// class channel_communicator { private: diff --git a/libs/full/collectives/include/hpx/collectives/communication_set.hpp b/libs/full/collectives/include/hpx/collectives/communication_set.hpp index f3353a08524f..d96a391a2dd1 100644 --- a/libs/full/collectives/include/hpx/collectives/communication_set.hpp +++ b/libs/full/collectives/include/hpx/collectives/communication_set.hpp @@ -4,12 +4,19 @@ // 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 communication_setup.hpp + #pragma once #if defined(DOXYGEN) -// clang-format off +/// Top level HPX namespace namespace hpx::collectives { + // clang-format off + + /// A handle identifying the communication channel to use for a particular + /// collective operation + struct communicator; /// The function \a create_communication_set sets up a (distributed) /// tree-like communication structure that can be used with any of the @@ -38,8 +45,8 @@ namespace hpx::collectives { this_site_arg this_site = this_site_arg(), generation_arg generation = generation_arg(), arity_arg arity = arity_arg()); -} -// clang-format on + // clang-format on +} // namespace hpx::collectives #else // DOXYGEN diff --git a/libs/full/collectives/include/hpx/collectives/create_communicator.hpp b/libs/full/collectives/include/hpx/collectives/create_communicator.hpp index 652cc4534612..d64b0bd7f255 100644 --- a/libs/full/collectives/include/hpx/collectives/create_communicator.hpp +++ b/libs/full/collectives/include/hpx/collectives/create_communicator.hpp @@ -12,6 +12,7 @@ #if defined(DOXYGEN) // clang-format off +/// Top level HPX namespace namespace hpx { namespace collectives { /// A communicator instance represents the list of sites that participate in @@ -30,7 +31,7 @@ namespace hpx { namespace collectives { /// Retrieve the number of used sites and the index of the current site /// for this communicator instance. - [[nodiscard] std::pair + [[nodiscard]] std::pair get_info() const noexcept; /// Return whether this communicator instance represents the root site @@ -139,9 +140,6 @@ struct hpx::util::extra_data_helper namespace hpx::collectives { - /////////////////////////////////////////////////////////////////////////// - /// a handle identifying the communication channel to use for a particular - /// collective operation struct communicator : hpx::components::client_base diff --git a/libs/full/collectives/include/hpx/collectives/latch.hpp b/libs/full/collectives/include/hpx/collectives/latch.hpp index 41f3ff2a1a7d..311aac31e477 100644 --- a/libs/full/collectives/include/hpx/collectives/latch.hpp +++ b/libs/full/collectives/include/hpx/collectives/latch.hpp @@ -4,8 +4,97 @@ // 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 hpx/collectives/latch.hpp + #pragma once +#if defined(DOXYGEN) +// clang-format off +namespace hpx { namespace distributed { + + /// Latch is an implementation of a synchronization primitive that allows + /// multiple threads to wait for a shared event to occur before proceeding. + /// This latch can be invoked in a distributed application. + /// + /// For a local only latch \see hpx::latch. + class HPX_EXPORT latch; + + /// Initialize the latch + /// + /// Requires: count >= 0. + /// Synchronization: None + /// Postconditions: counter_ == count. + /// + explicit latch(std::ptrdiff_t count); + + /// Extension: Create a client side representation for the existing + /// \a server#latch instance with the given global id \a id. + latch(hpx::id_type const& id); + + /// Extension: Create a client side representation for the existing + /// \a server#latch instance with the given global id \a id. + latch(hpx::future&& f); + + /// Extension: Create a client side representation for the existing + /// \a server#latch instance with the given global id \a id. + latch(hpx::shared_future const& id); + + /// Decrements counter_ by 1 . Blocks at the synchronization point + /// until counter_ reaches 0. + /// + /// Requires: counter_ > 0. + /// + /// Synchronization: Synchronizes with all calls that block on this + /// latch and with all is_ready calls on this latch that return true. + /// + /// \throws Nothing. + void count_down_and_wait(); + + /// Decrements counter_ by update . Blocks at the synchronization point + /// until counter_ reaches 0. + /// + /// Requires: counter_ > 0. + /// + /// Synchronization: Synchronizes with all calls that block on this + /// latch and with all is_ready calls on this latch that return true. + /// + /// \throws Nothing. + void arrive_and_wait(); + + /// Decrements counter_ by n. Does not block. + /// + /// Requires: counter_ >= n and n >= 0. + /// + /// Synchronization: Synchronizes with all calls that block on this + /// latch and with all is_ready calls on this latch that return true . + /// + /// \throws Nothing. + void count_down(std::ptrdiff_t n); + + /// Returns: counter_ == 0. Does not block. + /// + /// \throws Nothing. + bool is_ready() const noexcept; + + /// Returns: counter_ == 0. Does not block. + /// + /// \throws Nothing. + /// + bool try_wait() const noexcept; + + /// If counter_ is 0, returns immediately. Otherwise, blocks the + /// calling thread at the synchronization point until counter_ + /// reaches 0. + /// + /// \throws Nothing. + /// + void wait() const; + +}} // namespace hpx::distributed + +// clang-format on +#else + #include #include #include @@ -17,9 +106,13 @@ #include -/////////////////////////////////////////////////////////////////////////////// namespace hpx::distributed { + /// Latch is an implementation of a synchronization primitive that allows + /// multiple threads to wait for a shared event to occur before proceeding. + /// This latch can be invoked in a distributed application. + /// + /// For a local only latch \see hpx::latch. class HPX_EXPORT latch : public components::client_base { @@ -72,7 +165,6 @@ namespace hpx::distributed { /// latch and with all is_ready calls on this latch that return true. /// /// \throws Nothing. - /// void count_down_and_wait() { count_down_and_wait_async().get(); @@ -87,7 +179,6 @@ namespace hpx::distributed { /// latch and with all is_ready calls on this latch that return true. /// /// \throws Nothing. - /// void arrive_and_wait() { count_down_and_wait_async().get(); @@ -101,7 +192,6 @@ namespace hpx::distributed { /// latch and with all is_ready calls on this latch that return true . /// /// \throws Nothing. - /// void count_down(std::ptrdiff_t n) { count_down_async(n).get(); @@ -110,7 +200,6 @@ namespace hpx::distributed { /// Returns: counter_ == 0. Does not block. /// /// \throws Nothing. - /// bool is_ready() const noexcept { return is_ready_async().get(); @@ -166,3 +255,5 @@ namespace hpx::lcos { } // namespace hpx::lcos #include + +#endif // DOXYGEN diff --git a/libs/full/include/CMakeLists.txt b/libs/full/include/CMakeLists.txt index cb003216fc02..a50d376b62ea 100644 --- a/libs/full/include/CMakeLists.txt +++ b/libs/full/include/CMakeLists.txt @@ -14,6 +14,7 @@ set(include_headers hpx/algorithm.hpp hpx/barrier.hpp hpx/channel.hpp + hpx/collectives.hpp hpx/compute.hpp hpx/future.hpp hpx/hpx.hpp