# 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.

## Header hpx/collectives/all_gather.hpp¶

namespace hpx
namespace lcos

Functions

template<typename T>
hpx::future<std::vector<T>> all_gather(char const *basename, hpx::future<T> &&result, std::size_t num_sites = std::size_t(-1), std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1), std::size_t root_site = 0)

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.

Note

Each all_gather operation has to be accompanied with a unique usage of the HPX_REGISTER_ALLTOALL macro to define the necessary internal facilities used by all_gather.

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: A future referring to 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. 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<typename std::decay<T>::type>> all_gather(char const *basename, T &&result, std::size_t num_sites = std::size_t(-1), std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1), std::size_t root_site = 0)

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.

Note

Each all_gather operation has to be accompanied with a unique usage of the HPX_REGISTER_ALLTOALL macro to define the necessary internal facilities used by all_gather.

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. root_site The site that is responsible for creating the all_gather support object. This value is optional and defaults to ‘0’ (zero).

## Header hpx/collectives/all_reduce.hpp¶

namespace hpx
namespace lcos

Functions

template<typename T, typename F>
hpx::future<T> all_reduce(char const *basename, hpx::future<T> result, F &&op, std::size_t num_sites = std::size_t(-1), std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1), std::size_t root_site = 0)

AllReduce 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.

Note

Each all_reduce operation has to be accompanied with a unique usage of the HPX_REGISTER_ALLREDUCE macro to define the necessary internal facilities used by all_reduce.

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
• basename: The base name identifying the all_reduce operation

• local_result: A future referring to 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. 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(char const *basename, T &&result, F &&op, std::size_t num_sites = std::size_t(-1), std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1), std::size_t root_site = 0)

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.

Note

Each all_reduce operation has to be accompanied with a unique usage of the HPX_REGISTER_ALLREDUCE macro to define the necessary internal facilities used by all_reduce.

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. root_site The site that is responsible for creating the all_reduce support object. This value is optional and defaults to ‘0’ (zero).

## Header hpx/collectives/all_to_all.hpp¶

namespace hpx
namespace lcos

Functions

template<typename T>
hpx::future<std::vector<T>> all_to_all(char const *basename, hpx::future<std::vector<T>> &&result, std::size_t num_sites = std::size_t(-1), std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1), std::size_t root_site = 0)

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.

Note

Each all_to_all operation has to be accompanied with a unique usage of the HPX_REGISTER_ALLTOALL macro to define the necessary internal facilities used by all_to_all.

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: A future referring to 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. 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<typename std::decay<T>::type>> all_to_all(char const *basename, T &&result, std::size_t num_sites = std::size_t(-1), std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1), std::size_t root_site = 0)

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.

Note

Each all_to_all operation has to be accompanied with a unique usage of the HPX_REGISTER_ALLTOALL macro to define the necessary internal facilities used by all_to_all.

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. root_site The site that is responsible for creating the all_to_all support object. This value is optional and defaults to ‘0’ (zero).

## Header hpx/collectives/barrier.hpp¶

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.

## Header hpx/collectives/broadcast_direct.hpp¶

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, ...)

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, ...)

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.

## Header hpx/collectives/fold.hpp¶

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.

## Header hpx/collectives/gather.hpp¶

namespace hpx
namespace lcos

Functions

template<typename T>
hpx::future<std::vector<T>> gather_here(char const *basename, hpx::future<T> result, std::size_t num_sites = std::size_t(-1), std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1))

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.

Note

Each gather operation has to be accompanied with a unique usage of the HPX_REGISTER_GATHER macro to define the necessary internal facilities used by gather_here and gather_there

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: A future referring to 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<T>> gather_there(char const *basename, hpx::future<T> result, std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1), std::size_t root_site = 0)

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)

Note

Each gather operation has to be accompanied with a unique usage of the HPX_REGISTER_GATHER macro to define the necessary internal facilities used by gather_here and gather_there

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: A future referring to 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<typename std::decay<T>::type>> gather_here(char const *basename, T &&result, std::size_t num_sites = std::size_t(-1), std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1))

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.

Note

Each gather operation has to be accompanied with a unique usage of the HPX_REGISTER_GATHER macro to define the necessary internal facilities used by gather_here and gather_there

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<typename std::decay<T>::type>> gather_there(char const *basename, T &&result, std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1), std::size_t root_site = 0)

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)

Note

Each gather operation has to be accompanied with a unique usage of the HPX_REGISTER_GATHER macro to define the necessary internal facilities used by gather_here and gather_there

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.

## Header hpx/collectives/latch.hpp¶

namespace hpx
namespace lcos
class latch : public components::client_base<latch, lcos::server::latch>
#include <latch.hpp>

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

## Header hpx/collectives/reduce.hpp¶

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.

## Header hpx/collectives/scatter.hpp¶

namespace hpx
namespace lcos

Functions

template<typename T>
hpx::future<T> scatter_from(char const *basename, std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1), std::size_t root_site = 0)

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.

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

Note

Each scatter operation has to be accompanied with a unique usage of the HPX_REGISTER_SCATTER macro to define the necessary internal facilities used by scatter_from and scatter_to

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: A future referring to the value to transmit to the central scatter point from this call site.

• 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.

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

Note

Each scatter operation has to be accompanied with a unique usage of the HPX_REGISTER_SCATTER macro to define the necessary internal facilities used by scatter_from and scatter_to

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.

• 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_to(char const *basename, hpx::future<std::vector<T>> result, std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1))

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)

Note

Each scatter operation has to be accompanied with a unique usage of the HPX_REGISTER_SCATTER macro to define the necessary internal facilities used by scatter_from and scatter_to

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: A future referring to 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(char const *basename, std::vector<T> const &result, std::size_t num_sites = std::size_t(-1), std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1))

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)

Note

Each scatter operation has to be accompanied with a unique usage of the HPX_REGISTER_SCATTER macro to define the necessary internal facilities used by scatter_from and scatter_to

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(char const *basename, std::vector<T> &&result, std::size_t num_sites = std::size_t(-1), std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1))

## Header hpx/collectives/spmd_block.hpp¶

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 &&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 &policy, 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