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 6568cff
Show file tree
Hide file tree
Showing 8 changed files with 252 additions and 141 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
94 changes: 47 additions & 47 deletions libs/full/collectives/CMakeLists.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,56 +12,56 @@ list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")

# Default location is $HPX_ROOT/libs/collectives/include
set(collectives_headers
hpx/collectives/all_gather.hpp
hpx/collectives/all_reduce.hpp
hpx/collectives/all_to_all.hpp
hpx/collectives/argument_types.hpp
hpx/collectives/barrier.hpp
hpx/collectives/broadcast.hpp
hpx/collectives/broadcast_direct.hpp
hpx/collectives/communication_set.hpp
hpx/collectives/channel_communicator.hpp
hpx/collectives/create_communicator.hpp
hpx/collectives/detail/channel_communicator.hpp
hpx/collectives/detail/communication_set_node.hpp
hpx/collectives/detail/communicator.hpp
hpx/collectives/exclusive_scan.hpp
hpx/collectives/fold.hpp
hpx/collectives/gather.hpp
hpx/collectives/inclusive_scan.hpp
hpx/collectives/latch.hpp
hpx/collectives/reduce.hpp
hpx/collectives/reduce_direct.hpp
hpx/collectives/scatter.hpp
hpx/collectives/spmd_block.hpp
hpx/collectives/detail/barrier_node.hpp
hpx/collectives/detail/latch.hpp
hpx/collectives/all_gather.hpp
hpx/collectives/all_reduce.hpp
hpx/collectives/all_to_all.hpp
hpx/collectives/argument_types.hpp
hpx/collectives/barrier.hpp
hpx/collectives/broadcast.hpp
hpx/collectives/broadcast_direct.hpp
hpx/collectives/communication_set.hpp
hpx/collectives/channel_communicator.hpp
hpx/collectives/create_communicator.hpp
hpx/collectives/detail/channel_communicator.hpp
hpx/collectives/detail/communication_set_node.hpp
hpx/collectives/detail/communicator.hpp
hpx/collectives/exclusive_scan.hpp
hpx/collectives/fold.hpp
hpx/collectives/gather.hpp
hpx/collectives/inclusive_scan.hpp
hpx/collectives/latch.hpp
hpx/collectives/reduce.hpp
hpx/collectives/reduce_direct.hpp
hpx/collectives/scatter.hpp
hpx/collectives/spmd_block.hpp
hpx/collectives/detail/barrier_node.hpp
hpx/collectives/detail/latch.hpp
)

# 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
set(collectives_sources
barrier.cpp
create_communication_set.cpp
channel_communicator.cpp
create_communicator.cpp
latch.cpp
detail/barrier_node.cpp
detail/channel_communicator_server.cpp
detail/communication_set_node.cpp
barrier.cpp
create_communication_set.cpp
channel_communicator.cpp
create_communicator.cpp
latch.cpp
detail/barrier_node.cpp
detail/channel_communicator_server.cpp
detail/communication_set_node.cpp
)

include(HPX_AddModule)
Expand All @@ -72,12 +72,12 @@ add_hpx_module(
COMPAT_HEADERS ${collectives_compat_headers}
DEPENDENCIES hpx_core
MODULE_DEPENDENCIES
hpx_actions
hpx_actions_base
hpx_async_distributed
hpx_components
hpx_components_base
hpx_naming_base
hpx_runtime_distributed
hpx_actions
hpx_actions_base
hpx_async_distributed
hpx_components
hpx_components_base
hpx_naming_base
hpx_runtime_distributed
CMAKE_SUBDIRS examples tests
)
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
Loading

0 comments on commit 6568cff

Please sign in to comment.