Merge pull request #6352 from dimitraka/doc_updates

Add Public distributed API documentation
STEllAR-GROUP · Nov 8, 2023 · 3072a57 · 3072a57
2 parents 6b47c6e + 0fe7d38
commit 3072a57
Show file tree

Hide file tree

Showing 12 changed files with 432 additions and 92 deletions.
diff --git 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_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                                 |

diff --git a/docs/sphinx/api/public_distributed_api.rst b/docs/sphinx/api/public_distributed_api.rst
@@ -0,0 +1,179 @@
+..
+    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_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``
+=======================
+
+The header :hpx-header:`libs/full/include/include,hpx/collectives.hpp`
+contains definitions and implementations related to the collectives operations.
+
+Classes
+-------
+
+.. table:: `hpx` classes of header ``hpx/collectives.hpp``
+
+   +-----------------------------------------------------+
+   | Class                                               |
+   +=====================================================+
+   | :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:struct:`hpx::collectives::communicator`        |
+   +-----------------------------------------------------+
+   | :cpp:class:`hpx::collectives::channel_communicator` |
+   +-----------------------------------------------------+
+
+Functions
+---------
+
+.. 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::communicator::set_info`      |
+   +-----------------------------------------------------------+
+   | :cpp:func:`hpx::collectives::communicator::get_info`      |
+   +-----------------------------------------------------------+
+   | :cpp:func:`hpx::collectives::communicator::is_root`       |
+   +-----------------------------------------------------------+
+   | :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`                  |
+   +-----------------------------------------------------------+
+
+.. _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`                |
+   +---------------------------------------------------+
diff --git 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/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<detail::num_sites_tag>;
+
+    /// The local end of the communication channel
     using this_site_arg = detail::argument_type<detail::this_site_tag>;
+
+    /// The opposite end of the communication channel
     using that_site_arg = detail::argument_type<detail::that_site_tag>;
+
+    /// 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<detail::generation_tag>;
+
+    /// 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<detail::root_site_tag, 0>;
+
+    /// The tag identifying the concrete operation
     using tag_arg = detail::argument_type<detail::tag_tag, 0>;
+
+    /// The number of children each of the communication nodes is connected
+    /// to (default: picked based on num_sites).
     using arity_arg = detail::argument_type<detail::arity_tag>;
 }    // namespace hpx::collectives