create_communicator.hpp#

Defined in header hpx/collectives/create_communicator.hpp.

See Public API for a list of names and headers that are part of the public HPX API.

namespace hpx

Top level HPX namespace.

namespace collectives

Functions

communicator create_communicator(char const *basename, num_sites_arg num_sites = num_sites_arg(), this_site_arg this_site = this_site_arg(), generation_arg generation = generation_arg(), root_site_arg root_site = root_site_arg())#

Create a new communicator object usable with any collective operation

This functions creates a new communicator object that can be called in order to pre-allocate a communicator object usable with multiple invocations of the collective operations (such as all_gather, all_reduce, all_to_all, broadcast, etc.).

Parameters

basename – The base name identifying the collective operation
num_sites – The number of participating sites (default: all localities).
this_site – The sequence number of this invocation (usually the locality id). This value is optional and defaults to whatever hpx::get_locality_id() returns.
generation – The generational counter identifying the sequence number of the collective operation performed on the given base name. This is optional and needs to be supplied only if the collective operation on the given base name has to be performed more than once.
root_site – The site that is responsible for creating the collective support object. This value is optional and defaults to ‘0’ (zero).

Throws

hpx::exception – with hpx::error::bad_parameter if basename is null or empty, if the (resolved) num_sites is zero, if the (resolved) this_site is not smaller than num_sites, or if the (resolved) root_site does not designate a participating site.

Returns

This function returns a new communicator object usable with the collective operation.

communicator create_local_communicator(char const *basename, num_sites_arg num_sites, this_site_arg this_site, generation_arg generation = generation_arg(), root_site_arg root_site = root_site_arg())#

Create a new communicator object usable with any local collective operation

Parameters

basename – The base name identifying the collective operation
num_sites – The number of participating sites
this_site – The sequence number of this invocation (usually the sequence number of the object participating in the collective operation). This value must be in the range [0, num_sites).
generation – The generational counter identifying the sequence number of the collective operation performed on the given base name. This is optional and needs to be supplied only if the collective operation on the given base name has to be performed more than once.
root_site – The site that is responsible for creating the collective support object. This value is optional and defaults to ‘0’ (zero).

Throws

hpx::exception – with hpx::error::bad_parameter if basename is null or empty, if num_sites is unspecified or zero, if this_site is unspecified or not smaller than num_sites, or if the (resolved) root_site does not designate a participating site.

Returns

This function returns a new communicator object usable for all local collective operations.

hierarchical_communicator create_hierarchical_communicator(char const *basename, num_sites_arg num_sites = num_sites_arg(), this_site_arg this_site = this_site_arg(), arity_arg arity = arity_arg(), generation_arg generation = generation_arg(), root_site_arg root_site = root_site_arg(), flat_fallback_threshold_arg threshold = flat_fallback_threshold_arg())#

Create a new hierarchical communicator object usable with collective operations

This functions creates a new hierarchical_communicator object that can be called in order to pre-allocate a communicator object usable with multiple invocations of a collective operation (such as all_gather, all_reduce, all_to_all, broadcast, etc.).

Note

The sub-communicators of a hierarchical_communicator share one generation sequence per registered name. Every hierarchical collective advances each sub-communicator it touches by exactly two internal generations per call (a single-pass collective such as broadcast, gather, scatter or reduce, and the inter-group exchange of all_to_all, skip the second generation in one step rather than performing a second round-trip). A single hierarchical_communicator instance may therefore be shared freely across collective operations, provided every call uses an explicit, strictly consecutive generation number so the shared sequence stays gap-free. Because the two-phase hierarchical collectives (all_gather, all_reduce, all_to_all, inclusive_scan, exclusive_scan and the hierarchical barrier) derive their phase generations from that explicit number, they require it and reject an auto (default) generation. The non-hierarchical (flat) collectives keep supporting the default generation, falling back to the internal per-communicator counter maintained in the and_gate. Once any operation on a communicator has used that default, later operations on the same instance may no longer pass an explicit generation number: the counter’s position is no longer reliably known to the caller. The reverse transition, from explicit numbering back to the default, remains valid. All participants of a single operation must use the same generation mode.

Note

Hierarchical collective overloads that return hpx::future may still perform internal waits while walking the communicator tree. They should not be treated as fully non-blocking: validation failures are reported through the returned exceptional future, but internal phase hand-offs can throw or block before that future is delivered.

Parameters

basename – The base name identifying the collective operation
num_sites – The number of participating sites (default: all localities).
this_site – The sequence number of this invocation (usually the locality id). This value is optional and defaults to whatever hpx::get_locality_id() returns.
arity – The arity of the hierarchical tree of communicators to create for the given endpoint. The default arity is 2 and the value must be at least 2.
generation – The generational counter identifying the sequence number of the collective operation performed on the given base name. This is optional and needs to be supplied only if the collective operation on the given base name has to be performed more than once.
root_site – The site that is responsible for creating the collective support object. Hierarchical communicators currently support only site 0 as the root, which is also the default.
threshold – The site-count threshold below which the communicator collapses to a single flat communicator spanning all sites (strict comparison: num_sites < threshold). The default is 16; pass 0 to disable the fallback and always build a tree.

Throws

hpx::exception – with hpx::error::bad_parameter if basename is null or empty, if the (resolved) num_sites is zero, if the (resolved) this_site is not smaller than num_sites, if the (resolved) root_site is not zero, or if arity is smaller than 2.

Returns

This function returns a new communicator object usable with the collective operation.

struct communicator#

#include <create_communicator.hpp>

A communicator instance represents the list of sites that participate in a particular collective operation.

Public Functions

void set_info(num_sites_arg num_sites, this_site_arg this_site) noexcept#

Store the number of used sites and the index of the current site for this communicator instance.

Parameters

num_sites – The number of participating sites (default: all localities).
this_site – The sequence number of this site (usually the locality id).

std::pair<num_sites_arg, this_site_arg> get_info() const noexcept#: Retrieve the number of used sites and the index of the current site for this communicator instance.

bool is_root() const#: Return whether this communicator instance represents the root site of the communication operation.