collectives¶

The contents of this module can be included with the header hpx/modules/collectives.hpp. These headers may be used by user-code but are not guaranteed stable (neither header location nor contents). You are using these at your own risk. If you wish to use non-public functionality from a module we strongly suggest only including the module header hpx/modules/collectives.hpp, not the particular header in which the functionality you would like to use is defined. See Public API for a list of names that are part of the public HPX API.

namespace hpx

namespace collectives¶

Functions

template<typename T> hpx::future<std::vector<std::decay_t<T>>> all_gather(char const *basename, T &&result, 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())¶

AllGather a set of values from different call sites

This function receives a set of values from all call sites operating on the given base name.

Return

This function returns a future holding a vector with all values send by all participating sites. It will become ready once the all_gather operation has been completed.

Parameters

basename: The base name identifying the all_gather operation
local_result: The value to transmit to all participating sites from this call site.
num_sites: The number of participating sites (default: all localities).
generation: The generational counter identifying the sequence number of the all_gather operation performed on the given base name. This is optional and needs to be supplied only if the all_gather operation on the given base name has to be performed more than once.
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. \params root_site The site that is responsible for creating the all_gather support object. This value is optional and defaults to ‘0’ (zero).

template<typename T> hpx::future<std::vector<std::decay_t<T>>> all_gather(communicator comm, T &&result, this_site_arg this_site = this_site_arg())¶

AllGather a set of values from different call sites

This function receives a set of values from all call sites operating on the given base name.

Return

This function returns a future holding a vector with all values send by all participating sites. It will become ready once the all_gather operation has been completed.

Parameters

comm: A communicator object returned from create_reducer
local_result: The value to transmit to all participating sites from this call site.
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.

namespace hpx

namespace collectives

Functions

template<typename T, typename F> hpx::future<std::decay_t<T>> all_reduce(char const *basename, T &&result, F &&op, 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())¶

AllReduce a set of values from different call sites

This function receives a set of values from all call sites operating on the given base name.

Return

This function returns a future holding a vector with all values send by all participating sites. It will become ready once the all_reduce operation has been completed.

Parameters

basename: The base name identifying the all_reduce operation
local_result: The value to transmit to all participating sites from this call site.
op: Reduction operation to apply to all values supplied from all participating sites
num_sites: The number of participating sites (default: all localities).
generation: The generational counter identifying the sequence number of the all_reduce operation performed on the given base name. This is optional and needs to be supplied only if the all_reduce operation on the given base name has to be performed more than once.
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. \params root_site The site that is responsible for creating the all_reduce support object. This value is optional and defaults to ‘0’ (zero).

template<typename T, typename F> hpx::future<std::decay_t<T>> all_reduce(communicator comm, T &&result, F &&op, this_site_arg this_site = this_site_arg())¶

AllReduce a set of values from different call sites

This function receives a set of values from all call sites operating on the given base name.

Return

This function returns a future holding a vector with all values send by all participating sites. It will become ready once the all_reduce operation has been completed.

Parameters

comm: A communicator object returned from create_reducer
local_result: The value to transmit to all participating sites from this call site.
op: Reduction operation to apply to all values supplied from all participating sites
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.

namespace hpx

namespace collectives

Functions

template<typename T> hpx::future<std::vector<std::decay_t<T>>> all_to_all(char const *basename, T &&result, 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())¶

AllToAll a set of values from different call sites

This function receives a set of values from all call sites operating on the given base name.

Return

This function returns a future holding a vector with all values send by all participating sites. It will become ready once the all_to_all operation has been completed.

Parameters

basename: The base name identifying the all_to_all operation
local_result: The value to transmit to all participating sites from this call site.
num_sites: The number of participating sites (default: all localities).
generation: The generational counter identifying the sequence number of the all_to_all operation performed on the given base name. This is optional and needs to be supplied only if the all_to_all operation on the given base name has to be performed more than once.
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. \params root_site The site that is responsible for creating the all_to_all support object. This value is optional and defaults to ‘0’ (zero).

template<typename T> hpx::future<std::vector<std::decay_t<T>>> all_to_all(communicator comm, T &&result, this_site_arg this_site = this_site_arg())¶

AllToAll a set of values from different call sites

This function receives a set of values from all call sites operating on the given base name.

Return

This function returns a future holding a vector with all values send by all participating sites. It will become ready once the all_to_all operation has been completed.

Parameters

comm: A communicator object returned from create_reducer
local_result: The value to transmit to all participating sites from this call site.
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.

namespace hpx

namespace collectives

struct generation_arg¶

Public Functions

constexpr generation_arg(std::size_t generation = std::size_t(-1))¶

constexpr generation_arg &operator=(std::size_t generation)¶

constexpr operator std::size_t() const¶

Public Members

std::size_t generation_¶

struct num_sites_arg¶

Public Functions

constexpr num_sites_arg(std::size_t num_sites = std::size_t(-1))¶

constexpr num_sites_arg &operator=(std::size_t num_sites)¶

constexpr operator std::size_t() const¶

Public Members

std::size_t num_sites_¶

struct root_site_arg¶

Public Functions

constexpr root_site_arg(std::size_t root_site = std::size_t(0))¶

constexpr root_site_arg &operator=(std::size_t root_site)¶

constexpr operator std::size_t() const¶

Public Members

std::size_t root_site_¶

struct that_site_arg¶

Public Functions

constexpr that_site_arg(std::size_t that_site = std::size_t(-1))¶

constexpr that_site_arg &operator=(std::size_t that_site)¶

constexpr operator std::size_t() const¶

Public Members

std::size_t that_site_¶

struct this_site_arg¶

Public Functions

constexpr this_site_arg(std::size_t this_site = std::size_t(-1))¶

constexpr this_site_arg &operator=(std::size_t this_site)¶

constexpr operator std::size_t() const¶

Public Members

std::size_t this_site_¶

namespace hpx

namespace lcos

class barrier¶

#include <barrier.hpp>

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::lcos::local::barrier.

Public Functions

barrier(std::string const &base_name)¶

Creates a barrier, rank is locality id, size is number of localities

A barrier

base_name is created. It expects that hpx::get_num_localities() participate and the local rank is hpx::get_locality_id().

Parameters

base_name: The name of the barrier

barrier(std::string const &base_name, std::size_t num)¶

Creates a barrier with a given size, rank is locality id

A barrier

base_name is created. It expects that num participate and the local rank is hpx::get_locality_id().

Parameters

base_name: The name of the barrier
num: The number of participating threads

barrier(std::string const &base_name, std::size_t num, std::size_t rank)¶

Creates a barrier with a given size and rank

A barrier

base_name is created. It expects that num participate and the local rank is rank.

Parameters

base_name: The name of the barrier
num: The number of participating threads
rank: The rank of the calling site for this invocation

barrier(std::string const &base_name, std::vector<std::size_t> const &ranks, std::size_t rank)¶

Creates a barrier with a vector of ranks

A barrier

base_name is created. It expects that ranks.size() and the local rank is rank (must be contained in ranks).

Parameters

base_name: The name of the barrier
ranks: Gives a list of participating ranks (this could be derived from a list of locality ids
rank: The rank of the calling site for this invocation

void wait()¶

Wait until each participant entered the barrier. Must be called by all participants

Return: This function returns once all participants have entered the barrier (have called wait).

hpx::future<void> wait(hpx::launch::async_policy)¶

Wait until each participant entered the barrier. Must be called by all participants

Return: a future that becomes ready once all participants have entered the barrier (have called wait).

Public Static Functions

static void synchronize()¶

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.

namespace hpx

namespace collectives

Functions

template<typename T> hpx::future<void> broadcast_to(char const *basename, T &&local_result, num_sites_arg num_sites = num_sites_arg(), this_site_arg this_site = this_site_arg(), generation_arg generation = generation_arg())¶

Broadcast a value to different call sites

This function sends a set of values to all call sites operating on the given base name.

Return

This function returns a future that will become ready once the broadcast operation has been completed.

Parameters

basename: The base name identifying the broadcast operation
local_result: A value to transmit to all participating sites from this call site.
num_sites: The number of participating sites (default: all localities).
generation: The generational counter identifying the sequence number of the broadcast operation performed on the given base name. This is optional and needs to be supplied only if the broadcast operation on the given base name has to be performed more than once.
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.

template<typename T> hpx::future<void> broadcast_to(communicator comm, T &&local_result, this_site_arg this_site = this_site_arg())¶

Broadcast a value to different call sites

This function sends a set of values to all call sites operating on the given base name.

Return

This function returns a future that will become ready once the broadcast operation has been completed.

Parameters

comm: A communicator object returned from create_reducer
local_result: A value to transmit to all participating sites from this call site.
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.

template<typename T> hpx::future<T> broadcast_from(char const *basename, this_site_arg this_site = this_site_arg(), generation_arg generation = generation_arg())¶

Receive a value that was broadcast to different call sites

This function sends a set of values to all call sites operating on the given base name.

Return

This function returns a future holding the value that was sent to all participating sites. It will become ready once the broadcast operation has been completed.

Parameters

basename: The base name identifying the broadcast operation
generation: The generational counter identifying the sequence number of the broadcast operation performed on the given base name. This is optional and needs to be supplied only if the broadcast operation on the given base name has to be performed more than once.
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.

template<typename T> hpx::future<T> broadcast_from(communicator comm, this_site_arg this_site = this_site_arg())¶

Receive a value that was broadcast to different call sites

This function sends a set of values to all call sites operating on the given base name.

Return

This function returns a future holding the value that was sent to all participating sites. It will become ready once the broadcast operation has been completed.

Parameters

comm: A communicator object returned from create_reducer
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.

namespace hpx

namespace lcos

Functions

template<typename Action, typename ArgN, ...>hpx::future<std::vector<decltype(Action(hpx::id_type, ArgN, ...))> > hpx::lcos::broadcast(std::vector< hpx::id_type > const & ids, ArgN argN, ...)

Perform a distributed broadcast operation.

The function hpx::lcos::broadcast performs a distributed broadcast operation resulting in action invocations on a given set of global identifiers. The action can be either a plain action (in which case the global identifiers have to refer to localities) or a component action (in which case the global identifiers have to refer to instances of a component type which exposes the action.

The given action is invoked asynchronously on all given identifiers, and the arguments ArgN are passed along to those invocations.

Return

This function returns a future representing the result of the overall reduction operation.

Note

If decltype(Action(…)) is void, then the result of this function is future<void>.

Parameters

ids: [in] A list of global identifiers identifying the target objects for which the given action will be invoked.
argN: [in] Any number of arbitrary arguments (passed by const reference) which will be forwarded to the action invocation.

template<typename Action, typename ArgN, ...>void hpx::lcos::broadcast_apply(std::vector< hpx::id_type > const & ids, ArgN argN, ...)

Perform an asynchronous (fire&forget) distributed broadcast operation.

The function hpx::lcos::broadcast_apply performs an asynchronous (fire&forget) distributed broadcast operation resulting in action invocations on a given set of global identifiers. The action can be either a plain action (in which case the global identifiers have to refer to localities) or a component action (in which case the global identifiers have to refer to instances of a component type which exposes the action.

The given action is invoked asynchronously on all given identifiers, and the arguments ArgN are passed along to those invocations.

Parameters

ids: [in] A list of global identifiers identifying the target objects for which the given action will be invoked.
argN: [in] Any number of arbitrary arguments (passed by const reference) which will be forwarded to the action invocation.

template<typename Action, typename ArgN, ...>hpx::future< std::vector<decltype(Action(hpx::id_type, ArgN, ..., std::size_t))> > hpx::lcos::broadcast_with_index(std::vector< hpx::id_type > const & ids, ArgN argN, ...)

Perform a distributed broadcast operation.

The function hpx::lcos::broadcast_with_index performs a distributed broadcast operation resulting in action invocations on a given set of global identifiers. The action can be either a plain action (in which case the global identifiers have to refer to localities) or a component action (in which case the global identifiers have to refer to instances of a component type which exposes the action.

The given action is invoked asynchronously on all given identifiers, and the arguments ArgN are passed along to those invocations.

The function passes the index of the global identifier in the given list of identifiers as the last argument to the action.

Return

This function returns a future representing the result of the overall reduction operation.

Note

If decltype(Action(…)) is void, then the result of this function is future<void>.

Parameters

ids: [in] A list of global identifiers identifying the target objects for which the given action will be invoked.
argN: [in] Any number of arbitrary arguments (passed by const reference) which will be forwarded to the action invocation.

template<typename Action, typename ArgN, ...>void hpx::lcos::broadcast_apply_with_index(std::vector< hpx::id_type > const & ids, ArgN argN, ...)

Perform an asynchronous (fire&forget) distributed broadcast operation.

The function hpx::lcos::broadcast_apply_with_index performs an asynchronous (fire&forget) distributed broadcast operation resulting in action invocations on a given set of global identifiers. The action can be either a plain action (in which case the global identifiers have to refer to localities) or a component action (in which case the global identifiers have to refer to instances of a component type which exposes the action.

The given action is invoked asynchronously on all given identifiers, and the arguments ArgN are passed along to those invocations.

The function passes the index of the global identifier in the given list of identifiers as the last argument to the action.

Parameters

ids: [in] A list of global identifiers identifying the target objects for which the given action will be invoked.
argN: [in] Any number of arbitrary arguments (passed by const reference) which will be forwarded to the action invocation.

namespace hpx

namespace collectives

Functions

hpx::future<channel_communicator> create_channel_communicator(char const *basename, num_sites_arg num_sites = num_sites_arg(), this_site_arg this_site = this_site_arg())¶

Create a new communicator object usable with peer-to-peer channel-based operations

This functions creates a new communicator object that can be called in order to pre-allocate a communicator object usable with multiple invocations of channel-based peer-to-peer operations.

Return

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

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.

channel_communicator create_channel_communicator(hpx::launch::sync_policy, char const *basename, num_sites_arg num_sites = num_sites_arg(), this_site_arg this_site = this_site_arg())¶

Create a new communicator object usable with peer-to-peer channel-based operations

This functions creates a new communicator object that can be called in order to pre-allocate a communicator object usable with multiple invocations of channel-based peer-to-peer operations.

Return

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

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.

template<typename T> hpx::future<void> set(channel_communicator comm, that_site_arg site, T &&value)¶

Send a value to the given site

This function sends a value to the given site based on the given communicator.

Return

This function returns a future<void> that becomes ready once the data transfer operation has finished.

Parameters

comm: The channel communicator object to use for the data transfer
site: The destination site
value: The value to send

template<typename T> hpx::future<T> get(channel_communicator comm, that_site_arg site)¶

Send a value to the given site

This function receives a value from the given site based on the given communicator.

Return

This function returns a future<T> that becomes ready once the data transfer operation has finished. The future will hold the received value.

Parameters

comm: The channel communicator object to use for the data transfer
site: The source site

namespace hpx

namespace lcos

Functions

hpx::future<hpx::id_type> create_communication_set(char const *basename, std::size_t num_sites = std::size_t(-1), std::size_t this_site = std::size_t(-1), std::size_t arity = std::size_t(-1))¶

The function create_communication_set sets up a (distributed) tree-like communication structure that can be used with any of the collective APIs (such like all_to_all and similar).

Return

This function returns a future holding an id_type of the communicator object to be used on the current locality.

Parameters

basename: The base name identifying the all_to_all 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 number of children each of the communication nodes is connected to (default: picked based on num_sites)

namespace hpx

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 any of the collective operations (such as all_gather, all_reduce, all_to_all, broadcast, etc.).

Return

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

Parameters

basename: The base name identifying the collective operation
num_sites: The number of participating sites (default: all localities).
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.
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. \params root_site The site that is responsible for creating the collective support object. This value is optional and defaults to ‘0’ (zero).

namespace hpx

namespace collectives

Functions

template<typename T, typename F> hpx::future<std::decay_t<T>> exclusive_scan(char const *basename, T &&result, F &&op, 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())¶

Exclusive scan a set of values from different call sites

This function performs an exclusive scan operation on a set of values received from all call sites operating on the given base name.

Note

The result returned on the root_site is always the same as the result returned on thus_site == 1 and is the same as the value provided by the thje root_site.

Return

This function returns a future holding a vector with all values send by all participating sites. It will become ready once the exclusive_scan operation has been completed.

Parameters

basename: The base name identifying the exclusive_scan operation
local_result: The value to transmit to all participating sites from this call site.
op: Reduction operation to apply to all values supplied from all participating sites
num_sites: The number of participating sites (default: all localities).
generation: The generational counter identifying the sequence number of the exclusive_scan operation performed on the given base name. This is optional and needs to be supplied only if the exclusive_scan operation on the given base name has to be performed more than once.
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. \params root_site The site that is responsible for creating the exclusive_scan support object. This value is optional and defaults to ‘0’ (zero).

template<typename T, typename F> hpx::future<std::decay_t<T>> exclusive_scan(communicator comm, T &&result, F &&op, this_site_arg this_site = this_site_arg())¶

Exclusive scan a set of values from different call sites

This function performs an exclusive scan operation on a set of values received from all call sites operating on the given base name.

Note

The result returned on the root_site is always the same as the result returned on thus_site == 1 and is the same as the value provided by the thje root_site.

Return

This function returns a future holding a vector with all values send by all participating sites. It will become ready once the exclusive_scan operation has been completed.

Parameters

comm: A communicator object returned from create_reducer
local_result: The value to transmit to all participating sites from this call site.
op: Reduction operation to apply to all values supplied from all participating sites
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.

namespace hpx

namespace lcos

Functions

template<typename Action, typename FoldOp, typename Init, typename ArgN, ...>hpx::future<decltype(Action(hpx::id_type, ArgN, ...))> hpx::lcos::fold(std::vector< hpx::id_type > const & ids, FoldOp && fold_op, Init && init, ArgN argN, ...)

Perform a distributed fold operation.

The function hpx::lcos::fold performs a distributed folding operation over results returned from action invocations on a given set of global identifiers. The action can be either a plain action (in which case the global identifiers have to refer to localities) or a component action (in which case the global identifiers have to refer to instances of a component type which exposes the action.

Note

The type of the initial value must be convertible to the result type returned from the invoked action.

Return

This function returns a future representing the result of the overall folding operation.

Parameters

ids: [in] A list of global identifiers identifying the target objects for which the given action will be invoked.
fold_op: [in] A binary function expecting two results as returned from the action invocations. The function (or function object) is expected to return the result of the folding operation performed on its arguments.
init: [in] The initial value to be used for the folding operation
argN: [in] Any number of arbitrary arguments (passed by value, by const reference or by rvalue reference) which will be forwarded to the action invocation.

template<typename Action, typename FoldOp, typename Init, typename ArgN, ...>hpx::future<decltype(Action(hpx::id_type, ArgN, ..., std::size_t))> hpx::lcos::fold_with_index(std::vector< hpx::id_type > const & ids, FoldOp && fold_op, Init && init, ArgN argN, ...)

Perform a distributed folding operation.

The function hpx::lcos::fold_with_index performs a distributed folding operation over results returned from action invocations on a given set of global identifiers. The action can be either plain action (in which case the global identifiers have to refer to localities) or a component action (in which case the global identifiers have to refer to instances of a component type which exposes the action.

The function passes the index of the global identifier in the given list of identifiers as the last argument to the action.

Note

The type of the initial value must be convertible to the result type returned from the invoked action.

Return

This function returns a future representing the result of the overall folding operation.

Parameters

ids: [in] A list of global identifiers identifying the target objects for which the given action will be invoked.
fold_op: [in] A binary function expecting two results as returned from the action invocations. The function (or function object) is expected to return the result of the folding operation performed on its arguments.
init: [in] The initial value to be used for the folding operation
argN: [in] Any number of arbitrary arguments (passed by value, by const reference or by rvalue reference) which will be forwarded to the action invocation.

template<typename Action, typename FoldOp, typename Init, typename ArgN, ...>hpx::future<decltype(Action(hpx::id_type, ArgN, ...))> hpx::lcos::inverse_fold(std::vector< hpx::id_type > const & ids, FoldOp && fold_op, Init && init, ArgN argN, ...)

Perform a distributed inverse folding operation.

The function hpx::lcos::inverse_fold performs an inverse distributed folding operation over results returned from action invocations on a given set of global identifiers. The action can be either a plain action (in which case the global identifiers have to refer to localities) or a component action (in which case the global identifiers have to refer to instances of a component type which exposes the action.

Note

The type of the initial value must be convertible to the result type returned from the invoked action.

Return

This function returns a future representing the result of the overall folding operation.

Parameters

ids: [in] A list of global identifiers identifying the target objects for which the given action will be invoked.
fold_op: [in] A binary function expecting two results as returned from the action invocations. The function (or function object) is expected to return the result of the folding operation performed on its arguments.
init: [in] The initial value to be used for the folding operation
argN: [in] Any number of arbitrary arguments (passed by value, by const reference or by rvalue reference) which will be forwarded to the action invocation.

template<typename Action, typename FoldOp, typename Init, typename ArgN, ...>hpx::future<decltype(Action(hpx::id_type, ArgN, ..., std::size_t))> hpx::lcos::inverse_fold_with_index(std::vector< hpx::id_type > const & ids, FoldOp && fold_op, Init && init, ArgN argN, ...)

Perform a distributed inverse folding operation.

The function hpx::lcos::inverse_fold_with_index performs an inverse distributed folding operation over results returned from action invocations on a given set of global identifiers. The action can be either plain action (in which case the global identifiers have to refer to localities) or a component action (in which case the global identifiers have to refer to instances of a component type which exposes the action.

The function passes the index of the global identifier in the given list of identifiers as the last argument to the action.

Note

The type of the initial value must be convertible to the result type returned from the invoked action.

Return

This function returns a future representing the result of the overall folding operation.

Parameters

ids: [in] A list of global identifiers identifying the target objects for which the given action will be invoked.
fold_op: [in] A binary function expecting two results as returned from the action invocations. The function (or function object) is expected to return the result of the folding operation performed on its arguments.
init: [in] The initial value to be used for the folding operation
argN: [in] Any number of arbitrary arguments (passed by value, by const reference or by rvalue reference) which will be forwarded to the action invocation.

namespace hpx

namespace collectives

Functions

template<typename T> hpx::future<std::vector<decay_t<T>>> gather_here(char const *basename, T &&result, num_sites_arg num_sites = num_sites_arg(), this_site_arg this_site = this_site_arg(), generation_arg generation = generation_arg())¶

Gather a set of values from different call sites

This function receives a set of values from all call sites operating on the given base name.

Return

This function returns a future holding a vector with all gathered values. It will become ready once the gather operation has been completed.

Parameters

basename: The base name identifying the gather operation
result: The value to transmit to the central gather point from this call site.
num_sites: The number of participating sites (default: all localities).
generation: The generational counter identifying the sequence number of the gather operation performed on the given base name. This is optional and needs to be supplied only if the gather operation on the given base name has to be performed more than once.
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.

template<typename T> hpx::future<std::vector<decay_t<T>>> gather_here(communicator comm, T &&result, this_site_arg this_site = this_site_arg())¶

Gather a set of values from different call sites

This function receives a set of values from all call sites operating on the given base name.

Return

This function returns a future holding a vector with all gathered values. It will become ready once the gather operation has been completed.

Parameters

comm: A communicator object returned from create_reducer
result: The value to transmit to the central gather point from this call site.
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.

template<typename T> hpx::future<std::vector<decay_t<T>>> gather_there(char const *basename, T &&result, this_site_arg this_site = this_site_arg(), generation_arg generation = generation_arg(), root_site_arg root_site = root_site_arg())¶

Gather a given value at the given call site

This function transmits the value given by result to a central gather site (where the corresponding gather_here is executed)

Return

This function returns a future holding a vector with all gathered values. It will become ready once the gather operation has been completed.

Parameters

basename: The base name identifying the gather operation
result: The value to transmit to the central gather point from this call site.
generation: The generational counter identifying the sequence number of the gather operation performed on the given base name. This is optional and needs to be supplied only if the gather operation on the given base name has to be performed more than once.
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.
root_site: The sequence number of the central gather point (usually the locality id). This value is optional and defaults to 0.

template<typename T> hpx::future<std::vector<decay_t<T>>> gather_there(communicator comm, T &&result, this_site_arg this_site = this_site_arg())¶

Gather a given value at the given call site

This function transmits the value given by result to a central gather site (where the corresponding gather_here is executed)

Return

This function returns a future holding a vector with all gathered values. It will become ready once the gather operation has been completed.

Parameters

comm: A communicator object returned from create_reducer
result: The value to transmit to the central gather point from this call site.
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.

namespace hpx

namespace collectives

Functions

template<typename T, typename F> hpx::future<std::decay_t<T>> inclusive_scan(char const *basename, T &&result, F &&op, 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())¶

Inclusive inclusive_scan a set of values from different call sites

This function performs an inclusive scan operation on a set of values received from all call sites operating on the given base name.

Return

This function returns a future holding a vector with all values send by all participating sites. It will become ready once the inclusive_scan operation has been completed.

Parameters

basename: The base name identifying the inclusive_scan operation
local_result: The value to transmit to all participating sites from this call site.
op: Reduction operation to apply to all values supplied from all participating sites
num_sites: The number of participating sites (default: all localities).
generation: The generational counter identifying the sequence number of the inclusive_scan operation performed on the given base name. This is optional and needs to be supplied only if the inclusive_scan operation on the given base name has to be performed more than once.
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. \params root_site The site that is responsible for creating the inclusive_scan support object. This value is optional and defaults to ‘0’ (zero).

template<typename T, typename F> hpx::future<std::decay_t<T>> inclusive_scan(communicator comm, T &&result, F &&op, this_site_arg this_site = this_site_arg())¶

Inclusive inclusive_scan a set of values from different call sites

This function performs an inclusive scan operation on a set of values received from all call sites operating on the given base name.

Return

This function returns a future holding a vector with all values send by all participating sites. It will become ready once the inclusive_scan operation has been completed.

Parameters

comm: A communicator object returned from create_reducer
local_result: The value to transmit to all participating sites from this call site.
op: Reduction operation to apply to all values supplied from all participating sites
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.

namespace hpx

namespace lcos

class latch : public components::client_base<latch, lcos::server::latch>¶

Public Functions

latch()¶

latch(std::ptrdiff_t count)¶

Initialize the latch

Requires: count >= 0. Synchronization: None Postconditions: counter_ == count.

latch(naming::id_type const &id)¶: Extension: Create a client side representation for the existing server::latch instance with the given global id id.

latch(hpx::future<naming::id_type> &&f)¶: Extension: Create a client side representation for the existing server::latch instance with the given global id id.

latch(hpx::shared_future<naming::id_type> const &id)¶: Extension: Create a client side representation for the existing server::latch instance with the given global id id.

latch(hpx::shared_future<naming::id_type> &&id)¶

void count_down_and_wait()¶

Decrements counter_ by 1 . Blocks at the synchronization point until counter_ reaches 0.

Requires: counter_ > 0.

Synchronization: Synchronizes with all calls that block on this latch and with all is_ready calls on this latch that return true.

Exceptions

Nothing.:

void count_down(std::ptrdiff_t n)¶

Decrements counter_ by n. Does not block.

Requires: counter_ >= n and n >= 0.

Synchronization: Synchronizes with all calls that block on this latch and with all is_ready calls on this latch that return true .

Exceptions

Nothing.:

bool is_ready() const¶

Returns: counter_ == 0. Does not block.

Exceptions

Nothing.:

void wait() const¶

If counter_ is 0, returns immediately. Otherwise, blocks the calling thread at the synchronization point until counter_ reaches 0.

Exceptions

Nothing.:

Private Types

typedef components::client_base<latch, lcos::server::latch> base_type¶

namespace hpx

namespace collectives

Functions

template<typename T, typename F> hpx::future<std::decay_t<T>> reduce_here(char const *basename, T &&result, F &&op, num_sites_arg num_sites = num_sites_arg(), this_site_arg this_site = this_site_arg(), generation_arg generation = generation_arg())¶

Reduce a set of values from different call sites

This function receives a set of values from all call sites operating on the given base name.

Return

This function returns a future holding a vector with all values send by all participating sites. It will become ready once the all_reduce operation has been completed.

Parameters

basename: The base name identifying the all_reduce operation
local_result: A value to reduce on the central reduction point from this call site.
op: Reduction operation to apply to all values supplied from all participating sites
num_sites: The number of participating sites (default: all localities).
generation: The generational counter identifying the sequence number of the all_reduce operation performed on the given base name. This is optional and needs to be supplied only if the all_reduce operation on the given base name has to be performed more than once.
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.

template<typename T, typename F> hpx::future<decay_t<T>> reduce_here(communicator comm, T &&local_result, F &&op, this_site_arg this_site = this_site_arg())¶

Reduce a set of values from different call sites

This function receives a set of values that are the result of applying a given operator on values supplied from all call sites operating on the given base name.

Return

This function returns a future holding a value calculated based on the values send by all participating sites. It will become ready once the all_reduce operation has been completed.

Parameters

comm: A communicator object returned from create_communicator
local_result: A value to reduce on the root_site from this call site.
op: Reduction operation to apply to all values supplied from all participating sites
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.

template<typename T, typename F> hpx::future<void> reduce_there(char const *basename, T &&result, this_site_arg this_site = this_site_arg(), generation_arg generation = generation_arg(), root_site_arg root_site = root_site_arg())¶

Reduce a given value at the given call site

This function transmits the value given by result to a central reduce site (where the corresponding reduce_here is executed)

Return

This function returns a future<void>. It will become ready once the reduction operation has been completed.

Parameters

basename: The base name identifying the reduction operation
result: A future referring to the value to transmit to the central reduction point from this call site.
generation: The generational counter identifying the sequence number of the reduction operation performed on the given base name. This is optional and needs to be supplied only if the reduction operation on the given base name has to be performed more than once.
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.
root_site: The sequence number of the central reduction point (usually the locality id). This value is optional and defaults to 0.

template<typename T> hpx::future<void> reduce_there(communicator comm, T &&local_result, this_site_arg this_site = this_site_arg())¶

Reduce a given value at the given call site

This function transmits the value given by result to a central reduce site (where the corresponding reduce_here is executed)

Return

This function returns a future holding a value calculated based on the values send by all participating sites. It will become ready once the all_reduce operation has been completed.

Parameters

comm: A communicator object returned from create_communicator
local_result: A value to reduce on the central reduction point from this call site.
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.

namespace hpx

namespace lcos

Functions

template<typename Action, typename ReduceOp, typename ArgN, ...>hpx::future<decltype(Action(hpx::id_type, ArgN, ...))> hpx::lcos::reduce(std::vector< hpx::id_type > const & ids, ReduceOp && reduce_op, ArgN argN, ...)

Perform a distributed reduction operation.

The function hpx::lcos::reduce performs a distributed reduction operation over results returned from action invocations on a given set of global identifiers. The action can be either a plain action (in which case the global identifiers have to refer to localities) or a component action (in which case the global identifiers have to refer to instances of a component type which exposes the action.

Return

This function returns a future representing the result of the overall reduction operation.

Parameters

ids: [in] A list of global identifiers identifying the target objects for which the given action will be invoked.
reduce_op: [in] A binary function expecting two results as returned from the action invocations. The function (or function object) is expected to return the result of the reduction operation performed on its arguments.
argN: [in] Any number of arbitrary arguments (passed by by const reference) which will be forwarded to the action invocation.

template<typename Action, typename ReduceOp, typename ArgN, ...>hpx::future<decltype(Action(hpx::id_type, ArgN, ..., std::size_t))> hpx::lcos::reduce_with_index(std::vector< hpx::id_type > const & ids, ReduceOp && reduce_op, ArgN argN, ...)

Perform a distributed reduction operation.

The function hpx::lcos::reduce_with_index performs a distributed reduction operation over results returned from action invocations on a given set of global identifiers. The action can be either plain action (in which case the global identifiers have to refer to localities) or a component action (in which case the global identifiers have to refer to instances of a component type which exposes the action.

The function passes the index of the global identifier in the given list of identifiers as the last argument to the action.

Return

This function returns a future representing the result of the overall reduction operation.

Parameters

ids: [in] A list of global identifiers identifying the target objects for which the given action will be invoked.
reduce_op: [in] A binary function expecting two results as returned from the action invocations. The function (or function object) is expected to return the result of the reduction operation performed on its arguments.
argN: [in] Any number of arbitrary arguments (passed by by const reference) which will be forwarded to the action invocation.

namespace hpx

namespace collectives

Functions

template<typename T> hpx::future<T> scatter_from(char const *basename, this_site_arg this_site = this_site_arg(), generation_arg generation = generation_arg(), root_site_arg root_site = root_site_arg())¶

Scatter (receive) a set of values to different call sites

This function receives an element of a set of values operating on the given base name.

Return

This function returns a future holding a the scattered value. It will become ready once the scatter operation has been completed.

Parameters

basename: The base name identifying the scatter operation
generation: The generational counter identifying the sequence number of the scatter operation performed on the given base name. This is optional and needs to be supplied only if the scatter operation on the given base name has to be performed more than once.
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.
root_site: The sequence number of the central scatter point (usually the locality id). This value is optional and defaults to 0.

template<typename T> hpx::future<T> scatter_from(communicator comm, this_site_arg this_site = this_site_arg())¶

Scatter (receive) a set of values to different call sites

This function receives an element of a set of values operating on the given base name.

Return

This function returns a future holding a the scattered value. It will become ready once the scatter operation has been completed.

Parameters

comm: A communicator object returned from create_reducer
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.

template<typename T> hpx::future<T> scatter_to(char const *basename, std::vector<T> &&result, num_sites_arg num_sites = num_sites_arg(), this_site_arg this_site = this_site_arg(), generation_arg generation = generation_arg())¶

Scatter (send) a part of the value set at the given call site

This function transmits the value given by result to a central scatter site (where the corresponding scatter_from is executed)

Return

This function returns a future holding a the scattered value. It will become ready once the scatter operation has been completed.

Parameters

basename: The base name identifying the scatter operation
result: The value to transmit to the central scatter point from this call site.
num_sites: The number of participating sites (default: all localities).
generation: The generational counter identifying the sequence number of the scatter operation performed on the given base name. This is optional and needs to be supplied only if the scatter operation on the given base name has to be performed more than once.
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.

template<typename T> hpx::future<T> scatter_to(communicator comm, std::vector<T> &&result, this_site_arg this_site = this_site_arg())¶

Scatter (send) a part of the value set at the given call site

This function transmits the value given by result to a central scatter site (where the corresponding scatter_from is executed)

Return

This function returns a future holding a the scattered value. It will become ready once the scatter operation has been completed.

Parameters

comm: A communicator object returned from create_reducer
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.

namespace hpx

namespace lcos

Functions

template<typename F, typename ...Args> hpx::future<void> define_spmd_block(std::string &&name, std::size_t images_per_locality, F&&, Args&&... args)¶

struct spmd_block¶

#include <spmd_block.hpp>

The class spmd_block defines an interface for launching multiple images while giving handles to each image to interact with the remaining images. The define_spmd_block function templates create multiple images of a user-defined action and launches them in a possibly separate thread. A temporary spmd block object is created and diffused to each image. The constraint for the action given to the define_spmd_block function is to accept a spmd_block as first parameter.

Public Functions

spmd_block()¶

spmd_block(std::string const &name, std::size_t images_per_locality, std::size_t num_images, std::size_t image_id)¶

std::size_t get_images_per_locality() const¶

std::size_t get_num_images() const¶

std::size_t this_image() const¶

void sync_all() const¶

hpx::future<void> sync_all(hpx::launch::async_policy const&) const¶

void sync_images(std::set<std::size_t> const &images) const¶

void sync_images(std::vector<std::size_t> const &input_images) const¶

template<typename Iterator> std::enable_if<traits::is_input_iterator<Iterator>::value>::type sync_images(Iterator begin, Iterator end) const¶

template<typename ...I> std::enable_if<util::all_of<typename std::is_integral<I>::type...>::value>::type sync_images(I... i)¶

hpx::future<void> sync_images(hpx::launch::async_policy const&, std::set<std::size_t> const &images) const¶

hpx::future<void> sync_images(hpx::launch::async_policy const &policy, std::vector<std::size_t> const &input_images) const¶

template<typename Iterator> std::enable_if<traits::is_input_iterator<Iterator>::value, hpx::future<void>>::type sync_images(hpx::launch::async_policy const &policy, Iterator begin, Iterator end) const¶

template<typename ...I> std::enable_if<util::all_of<typename std::is_integral<I>::type...>::value, hpx::future<void>>::type sync_images(hpx::launch::async_policy const &policy, I... i) const¶

Private Types

using barrier_type = hpx::lcos::barrier ¶

using table_type = std::map<std::set<std::size_t>, std::shared_ptr<barrier_type>>¶

Private Functions

template<typename Archive> void serialize(Archive&, unsigned)¶

Private Members

std::string name_¶

std::size_t images_per_locality_¶

std::size_t num_images_¶

std::size_t image_id_¶

hpx::util::jenkins_hash hash_¶

std::shared_ptr<hpx::lcos::barrier> barrier_¶

table_type barriers_¶

Friends

friend hpx::lcos::hpx::serialization::access