Skip to content

Commit

Permalink
Add documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@dimitraka
dimitraka committed Nov 7, 2023
1 parent a35e58f commit 0fe7d38
Show file tree
Hide file tree
Showing 8 changed files with 213 additions and 102 deletions.
12 changes: 5 additions & 7 deletions docs/sphinx/api/public_distributed_api.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ Classes
.. table:: `hpx` classes of header ``hpx/collectives.hpp``

+-----------------------------------------------------+
| Class |
| Class |
+=====================================================+
| :cpp:struct:`hpx::collectives::num_sites_arg` |
+-----------------------------------------------------+
Expand All @@ -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
---------
Expand Down Expand Up @@ -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` |
+-----------------------------------------------------------+
Expand Down
16 changes: 8 additions & 8 deletions libs/full/collectives/CMakeLists.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
148 changes: 82 additions & 66 deletions libs/full/collectives/include/hpx/collectives/barrier.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<std::size_t> 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<void> 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 <hpx/config.hpp>
#include <hpx/async_base/launch_policy.hpp>
#include <hpx/collectives/detail/barrier_node.hpp>
Expand All @@ -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<wrapped_type> 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<std::size_t> 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<void> wait(hpx::launch::async_policy) const;

/// \cond NOINTERNAL
// Resets this barrier instance.
void release();

Expand All @@ -116,32 +141,23 @@ namespace hpx::distributed {
// Get the instance of the global barrier
static std::array<barrier, 2>& get_global_barrier();
static std::array<barrier, 2> 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<wrapping_type> 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 <hpx/config/warnings_suffix.hpp>

#endif // DOXYGEN
18 changes: 9 additions & 9 deletions libs/full/collectives/include/hpx/collectives/channel_communicator.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,14 @@
#include <hpx/config.hpp>

#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
Expand Down Expand Up @@ -91,9 +97,8 @@ namespace hpx { namespace collectives {
template <typename T>
hpx::future<T> get(channel_communicator comm, that_site_arg site,
tag_arg tag = tag_arg());

}}
// clang-format on
// clang-format on
}} // namespace hpx::collectives

#else

Expand All @@ -112,13 +117,9 @@ namespace hpx { namespace collectives {
#include <utility>
#include <vector>

///////////////////////////////////////////////////////////////////////////////
namespace hpx { namespace collectives {

///////////////////////////////////////////////////////////////////////////
// forward declarations
/// a handle identifying the communication channel to use for get/set
/// operations
class channel_communicator;

template <typename T>
Expand All @@ -129,7 +130,6 @@ namespace hpx { namespace collectives {
hpx::future<void> set(
channel_communicator, that_site_arg, T&&, tag_arg = tag_arg());

///////////////////////////////////////////////////////////////////////////
class channel_communicator
{
private:
Expand Down
13 changes: 10 additions & 3 deletions libs/full/collectives/include/hpx/collectives/communication_set.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down
6 changes: 2 additions & 4 deletions libs/full/collectives/include/hpx/collectives/create_communicator.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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<num_sites_arg, this_site_arg>
[[nodiscard]] std::pair<num_sites_arg, this_site_arg>
get_info() const noexcept;

/// Return whether this communicator instance represents the root site
Expand Down Expand Up @@ -139,9 +140,6 @@ struct hpx::util::extra_data_helper<hpx::collectives::detail::communicator_data>

namespace hpx::collectives {

///////////////////////////////////////////////////////////////////////////
/// a handle identifying the communication channel to use for a particular
/// collective operation
struct communicator
: hpx::components::client_base<communicator, detail::communicator_server,
detail::communicator_data>
Expand Down
Loading

0 comments on commit 0fe7d38

Please sign in to comment.