Skip to content

Commit 3072a57

Browse files
hkaiserhkaiser
authored
Merge pull request #6352 from dimitraka/doc_updates
Add Public distributed API documentation
2 parents 6b47c6e + 0fe7d38 commit 3072a57

File tree

12 files changed

+432
-92
lines changed

12 files changed

+432
-92
lines changed

‎docs/sphinx/api.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,11 @@ a heading brings in the features listed under that heading.
5959

6060
api/public_api.rst
6161

62+
.. toctree::
63+
:maxdepth: 1
64+
65+
api/public_distributed_api.rst
66+
6267
.. toctree::
6368
:maxdepth: 1
6469

‎docs/sphinx/api/public_api.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -524,7 +524,7 @@ Classes
524524
:cpp:class:`hpx::promise`, but will eventually refer to
525525
:cpp:class:`hpx::promise` after a deprecation period.
526526

527-
.. table:: Distributed implementation of classes of header ``hpx/latch.hpp``
527+
.. table:: Distributed implementation of classes of header ``hpx/future.hpp``
528528

529529
+---------------------------------------+
530530
| Class |

‎docs/sphinx/api/public_distributed_api.rst

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
..
2+
Copyright (C) 2023 Dimitra Karatza
3+
4+
SPDX-License-Identifier: BSL-1.0
5+
Distributed under the Boost Software License, Version 1.0. (See accompanying
6+
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7+
8+
.. _public_distributed_api:
9+
10+
======================
11+
Public distributed API
12+
======================
13+
14+
Our Public Distributed API offers a rich set of tools and functions that enable developers
15+
to harness the full potential of distributed computing. Here, you'll find a comprehensive
16+
list of header files, classes and functions for various distributed computing features
17+
provided by |hpx|.
18+
19+
.. _public_distr_api_header_barrier:
20+
21+
``hpx/barrier.hpp``
22+
===================
23+
24+
The header :hpx-header:`libs/full/include/include,hpx/barrier.hpp` includes
25+
a distributed barrier implementation. For information regarding the C++ standard
26+
library header :cppreference-header:`barrier`, see :ref:`public_api`.
27+
28+
Classes
29+
-------
30+
31+
.. table:: Distributed implementation of classes of header ``hpx/barrier.hpp``
32+
33+
+----------------------------------------+
34+
| Class |
35+
+========================================+
36+
| :cpp:class:`hpx::distributed::barrier` |
37+
+----------------------------------------+
38+
39+
Functions
40+
---------
41+
42+
.. table:: `hpx` functions of header ``hpx/barrier.hpp``
43+
44+
+-------------------------------------------+
45+
| Function |
46+
+===========================================+
47+
| :cpp:func:`hpx::distributed::wait` |
48+
+-------------------------------------------+
49+
| :cpp:func:`hpx::distributed::synchronize` |
50+
+-------------------------------------------+
51+
52+
.. _public_distr_api_header_collectives:
53+
54+
``hpx/collectives.hpp``
55+
=======================
56+
57+
The header :hpx-header:`libs/full/include/include,hpx/collectives.hpp`
58+
contains definitions and implementations related to the collectives operations.
59+
60+
Classes
61+
-------
62+
63+
.. table:: `hpx` classes of header ``hpx/collectives.hpp``
64+
65+
+-----------------------------------------------------+
66+
| Class |
67+
+=====================================================+
68+
| :cpp:struct:`hpx::collectives::num_sites_arg` |
69+
+-----------------------------------------------------+
70+
| :cpp:struct:`hpx::collectives::this_site_arg` |
71+
+-----------------------------------------------------+
72+
| :cpp:struct:`hpx::collectives::that_site_arg` |
73+
+-----------------------------------------------------+
74+
| :cpp:struct:`hpx::collectives::generation_arg` |
75+
+-----------------------------------------------------+
76+
| :cpp:struct:`hpx::collectives::root_site_arg` |
77+
+-----------------------------------------------------+
78+
| :cpp:struct:`hpx::collectives::tag_arg` |
79+
+-----------------------------------------------------+
80+
| :cpp:struct:`hpx::collectives::arity_arg` |
81+
+-----------------------------------------------------+
82+
| :cpp:struct:`hpx::collectives::communicator` |
83+
+-----------------------------------------------------+
84+
| :cpp:class:`hpx::collectives::channel_communicator` |
85+
+-----------------------------------------------------+
86+
87+
Functions
88+
---------
89+
90+
.. table:: `hpx` functions of header ``hpx/collectives.hpp``
91+
92+
+-----------------------------------------------------------+
93+
| Function |
94+
+===========================================================+
95+
| :cpp:func:`hpx::collectives::all_gather` |
96+
+-----------------------------------------------------------+
97+
| :cpp:func:`hpx::collectives::all_reduce` |
98+
+-----------------------------------------------------------+
99+
| :cpp:func:`hpx::collectives::all_to_all` |
100+
+-----------------------------------------------------------+
101+
| :cpp:func:`hpx::collectives::broadcast_to` |
102+
+-----------------------------------------------------------+
103+
| :cpp:func:`hpx::collectives::broadcast_from` |
104+
+-----------------------------------------------------------+
105+
| :cpp:func:`hpx::collectives::create_channel_communicator` |
106+
+-----------------------------------------------------------+
107+
| :cpp:func:`hpx::collectives::set` |
108+
+-----------------------------------------------------------+
109+
| :cpp:func:`hpx::collectives::get` |
110+
+-----------------------------------------------------------+
111+
| :cpp:func:`hpx::collectives::create_communication_set` |
112+
+-----------------------------------------------------------+
113+
| :cpp:func:`hpx::collectives::create_communicator` |
114+
+-----------------------------------------------------------+
115+
| :cpp:func:`hpx::collectives::create_local_communicator` |
116+
+-----------------------------------------------------------+
117+
| :cpp:func:`hpx::collectives::communicator::set_info` |
118+
+-----------------------------------------------------------+
119+
| :cpp:func:`hpx::collectives::communicator::get_info` |
120+
+-----------------------------------------------------------+
121+
| :cpp:func:`hpx::collectives::communicator::is_root` |
122+
+-----------------------------------------------------------+
123+
| :cpp:func:`hpx::collectives::exclusive_scan` |
124+
+-----------------------------------------------------------+
125+
| :cpp:func:`hpx::collectives::gather_here` |
126+
+-----------------------------------------------------------+
127+
| :cpp:func:`hpx::collectives::gather_there` |
128+
+-----------------------------------------------------------+
129+
| :cpp:func:`hpx::collectives::inclusive_scan` |
130+
+-----------------------------------------------------------+
131+
| :cpp:func:`hpx::collectives::reduce_here` |
132+
+-----------------------------------------------------------+
133+
| :cpp:func:`hpx::collectives::reduce_there` |
134+
+-----------------------------------------------------------+
135+
| :cpp:func:`hpx::collectives::scatter_from` |
136+
+-----------------------------------------------------------+
137+
| :cpp:func:`hpx::collectives::scatter_to` |
138+
+-----------------------------------------------------------+
139+
140+
.. _public_distr_api_header_latch:
141+
142+
``hpx/latch.hpp``
143+
=================
144+
145+
The header :hpx-header:`libs/full/include/include,hpx/latch.hpp` includes
146+
a distributed latch implementation. For information regarding the C++ standard
147+
library header :cppreference-header:`latch`, see :ref:`public_api`.
148+
149+
Classes
150+
-------
151+
152+
.. table:: Distributed implementation of classes of header ``hpx/latch.hpp``
153+
154+
+--------------------------------------+
155+
| Class |
156+
+======================================+
157+
| :cpp:class:`hpx::distributed::latch` |
158+
+--------------------------------------+
159+
160+
Functions
161+
---------
162+
163+
.. table:: `hpx` functions of header ``hpx/latch.hpp``
164+
165+
+---------------------------------------------------+
166+
| Function |
167+
+===================================================+
168+
| :cpp:func:`hpx::distributed::count_down_and_wait` |
169+
+---------------------------------------------------+
170+
| :cpp:func:`hpx::distributed::arrive_and_wait` |
171+
+---------------------------------------------------+
172+
| :cpp:func:`hpx::distributed::count_down` |
173+
+---------------------------------------------------+
174+
| :cpp:func:`hpx::distributed::is_ready` |
175+
+---------------------------------------------------+
176+
| :cpp:func:`hpx::distributed::try_wait` |
177+
+---------------------------------------------------+
178+
| :cpp:func:`hpx::distributed::wait` |
179+
+---------------------------------------------------+

‎libs/full/collectives/CMakeLists.txt

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -41,15 +41,15 @@ set(collectives_headers
4141
# Default location is $HPX_ROOT/libs/collectives/include_compatibility
4242
# cmake-format: off
4343
set(collectives_compat_headers
44-
hpx/collectives.hpp => hpx/include/lcos.hpp
45-
hpx/lcos/barrier.hpp => hpx/barrier.hpp
46-
hpx/lcos/broadcast.hpp => hpx/include/lcos.hpp
47-
hpx/lcos/fold.hpp => hpx/include/lcos.hpp
48-
hpx/lcos/gather.hpp => hpx/include/lcos.hpp
49-
hpx/lcos/latch.hpp => hpx/latch.hpp
50-
hpx/lcos/reduce.hpp => hpx/include/lcos.hpp
51-
hpx/lcos/spmd_block.hpp => hpx/include/lcos.hpp
44+
hpx/lcos/barrier.hpp => hpx/barrier.hpp
45+
hpx/lcos/broadcast.hpp => hpx/include/lcos.hpp
46+
hpx/lcos/fold.hpp => hpx/include/lcos.hpp
47+
hpx/lcos/gather.hpp => hpx/include/lcos.hpp
48+
hpx/lcos/latch.hpp => hpx/latch.hpp
49+
hpx/lcos/reduce.hpp => hpx/include/lcos.hpp
50+
hpx/lcos/spmd_block.hpp => hpx/include/lcos.hpp
5251
)
52+
5353
# cmake-format: on
5454

5555
# Default location is $HPX_ROOT/libs/collectives/src

‎libs/full/collectives/include/hpx/collectives/argument_types.hpp

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,11 +50,29 @@ namespace hpx::collectives {
5050
struct arity_tag;
5151
} // namespace detail
5252

53+
/// The number of participating sites (default: all localities)
5354
using num_sites_arg = detail::argument_type<detail::num_sites_tag>;
55+
56+
/// The local end of the communication channel
5457
using this_site_arg = detail::argument_type<detail::this_site_tag>;
58+
59+
/// The opposite end of the communication channel
5560
using that_site_arg = detail::argument_type<detail::that_site_tag>;
61+
62+
/// The generational counter identifying the sequence number of the
63+
/// operation performed on the given base name. It needs to be supplied
64+
/// only if the operation on the given base name has to be performed
65+
/// more than once. It must be a positive number greater than zero.
5666
using generation_arg = detail::argument_type<detail::generation_tag>;
67+
68+
/// The site that is responsible for creating the support object
69+
/// of the operation. It defaults to '0' (zero).
5770
using root_site_arg = detail::argument_type<detail::root_site_tag, 0>;
71+
72+
/// The tag identifying the concrete operation
5873
using tag_arg = detail::argument_type<detail::tag_tag, 0>;
74+
75+
/// The number of children each of the communication nodes is connected
76+
/// to (default: picked based on num_sites).
5977
using arity_arg = detail::argument_type<detail::arity_tag>;
6078
} // namespace hpx::collectives

0 commit comments

Comments
 (0)