vt::collective::reduce::Reduce struct
#include <src/vt/collective/reduce/reduce.h>

A specific, isolated reducer instance for a given scope that sequences reduce operations via the reduction stamp within that scope.

Holds the state as a reduction makes it up the spanning tree until it reaches the root. Combines messages with the user-specified reduction operator as they move up the spanning tree.

The interaction between the reduction implementation's message buffering and termination detection may be unintuitive. It is believed and demonstrated to operate as intended, based on the following reasoning.

  • There is some epoch reduce_epoch
  • We assume all contributions to a given reduction (via reduce() calls) occur in reduce_epoch
  • Proposition: The result of the reduction will be delivered in reduce_epoch, and reduce_epoch will not terminate before that result is delivered.
  • On any given node, some local contribution to the reduction will be the last. That last contribution runs in reduce_epoch, which cannot have terminated before it runs.
  • On a leaf node, the reduction message up the spanning tree will be produced and sent in reduce_epoch.
  • At every interior node in the spanning tree, all reduction messages will be received and processed in reduce_epoch.
  • The reduction message passed up the spanning tree from every node will thus be produced and sent in reduce_epoch.
  • The root of the spanning tree will receive and process the last reduction message in reduce_epoch, passing it to the callback.

Base classes

struct vt::collective::tree::Tree virtual
General interface for storing a spanning tree.

Public types

using ReduceStateType = ReduceState
using ReduceNumType = typename ReduceStateType::ReduceNumType
using PendingSendType = messaging::PendingSend

Constructors, destructors, conversion operators

Reduce(detail::ReduceScope const& in_scope) explicit
Construct a new reducer instance.
Reduce(detail::ReduceScope const& in_scope, collective::tree::Tree* in_tree)
Construct a new reducer instance with a custom (or non-global) spanning tree.

Public functions

auto generateNextID() -> detail::ReduceStamp
Generate the next reduction stamp.
template<typename MsgT, ActiveTypedFnType<MsgT>* f>
auto reduce(NodeType root, MsgT*const msg, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType num_contrib = 1) -> PendingSendType
Reduce a message up the tree, possibly delayed through a pending send.
template<auto f>
auto reduce(NodeType root, typename FuncTraits<decltype(f)>::MsgT*const msg, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType num_contrib = 1) -> PendingSendType
Reduce a message up the tree, possibly delayed through a pending send.
template<auto f, template<typename Arg> class Op = NoneOp, typename... Params>
auto reduce(Node root, Params && ... params) -> PendingSendType
Perform a reduction without a message.
template<typename Op, auto f, typename... Params>
auto reduce(Node root, Params && ... params) -> PendingSendType
template<typename MsgT, ActiveTypedFnType<MsgT>* f>
auto reduceImmediate(NodeType root, MsgT*const msg, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType num_contrib = 1) -> detail::ReduceStamp
Reduce a message up the tree.
template<auto f>
auto reduceImmediate(NodeType root, typename FuncTraits<decltype(f)>::MsgT*const msg, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType num_contrib = 1) -> detail::ReduceStamp
Reduce a message up the tree.
template<typename OpT, typename MsgT, ActiveTypedFnType<MsgT>* f>
auto reduce(NodeType const& root, MsgT* msg, Callback<MsgT> cb, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType const& num_contrib = 1) -> PendingSendType
Reduce a message up the tree.
template<typename OpT, typename MsgT>
auto reduce(NodeType const& root, MsgT* msg, Callback<MsgT> cb, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType const& num_contrib = 1) -> PendingSendType
template<typename OpT, auto f>
auto reduce(NodeType const& root, typename FuncTraits<decltype(f)>::MsgT* msg, Callback<typename FuncTraits<decltype(f)>::MsgT> cb, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType const& num_contrib = 1) -> PendingSendType
Reduce a message up the tree.
template<typename OpT, typename MsgT, ActiveTypedFnType<MsgT>* f>
auto reduceImmediate(NodeType const& root, MsgT* msg, Callback<MsgT> cb, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType const& num_contrib = 1) -> detail::ReduceStamp
Reduce a message up the tree.
template<typename OpT, typename MsgT>
auto reduceImmediate(NodeType const& root, MsgT* msg, Callback<MsgT> cb, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType const& num_contrib = 1) -> detail::ReduceStamp
template<typename OpT, auto f>
auto reduceImmediate(NodeType const& root, typename FuncTraits<decltype(f)>::MsgT* msg, Callback<typename FuncTraits<decltype(f)>::MsgT> cb, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType const& num_contrib = 1) -> detail::ReduceStamp
Reduce a message up the tree.
template<typename OpT, typename FunctorT, typename MsgT, ActiveTypedFnType<MsgT>* f>
auto reduce(NodeType const& root, MsgT* msg, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType const& num_contrib = 1) -> PendingSendType
Reduce a message up the tree with a target function on the root node.
template<typename OpT, typename FunctorT, typename MsgT>
auto reduce(NodeType const& root, MsgT* msg, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType const& num_contrib = 1) -> PendingSendType
template<typename OpT, typename FunctorT, auto f>
auto reduce(NodeType const& root, typename FuncTraits<decltype(f)>::MsgT* msg, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType const& num_contrib = 1) -> PendingSendType
Reduce a message up the tree with a target function on the root node.
template<typename OpT, typename FunctorT, typename MsgT, ActiveTypedFnType<MsgT>* f>
auto reduceImmediate(NodeType const& root, MsgT* msg, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType const& num_contrib = 1) -> detail::ReduceStamp
Reduce a message up the tree with a target function on the root node.
template<typename OpT, typename FunctorT, typename MsgT>
auto reduceImmediate(NodeType const& root, MsgT* msg, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType const& num_contrib = 1) -> detail::ReduceStamp
template<typename OpT, typename FunctorT, auto f>
auto reduceImmediate(NodeType const& root, typename FuncTraits<decltype(f)>::MsgT* msg, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType const& num_contrib = 1) -> detail::ReduceStamp
Reduce a message up the tree with a target function on the root node.
template<typename MsgT>
void reduceAddMsg(MsgT* msg, bool const local, ReduceNumType num_contrib = -1)
Combine in a new message for a given reduction.
template<typename MsgT>
void reduceNewMsg(MsgT* msg)
Combine and send up the tree if ready.
template<typename MsgT>
void startReduce(detail::ReduceStamp id, bool use_num_contrib = true)
Explicitly start the reduction when the number of contributions is not known up front.
template<typename MsgT>
void reduceRootRecv(MsgT* msg)
Active function when a message reaches the root of the spanning tree and the reduction is complete.
template<typename MsgT>
void reduceUpHan(MsgT* msg)
Active function when a message arrives for a given scope at some level in the spanning tree.

Function documentation

vt::collective::reduce::Reduce::Reduce(detail::ReduceScope const& in_scope) explicit

Construct a new reducer instance.

Parameters
in_scope in the scope for the reducer

vt::collective::reduce::Reduce::Reduce(detail::ReduceScope const& in_scope, collective::tree::Tree* in_tree)

Construct a new reducer instance with a custom (or non-global) spanning tree.

Parameters
in_scope in the scope for the reducer
in_tree in the spanning tree

detail::ReduceStamp vt::collective::reduce::Reduce::generateNextID()

Generate the next reduction stamp.

Returns the stamp

template<typename MsgT, ActiveTypedFnType<MsgT>* f>
PendingSendType vt::collective::reduce::Reduce::reduce(NodeType root, MsgT*const msg, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType num_contrib = 1)

Reduce a message up the tree, possibly delayed through a pending send.

Parameters
root in the root node where the final handler provides the result
msg in the message to reduce on this node
id in the reduction stamp (optional), provided if out-of-order
num_contrib in number of expected contributions from this node
Returns the pending send corresponding to the reduce

template<auto f>
PendingSendType vt::collective::reduce::Reduce::reduce(NodeType root, typename FuncTraits<decltype(f)>::MsgT*const msg, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType num_contrib = 1)

Reduce a message up the tree, possibly delayed through a pending send.

Parameters
root in the root node where the final handler provides the result
msg in the message to reduce on this node
id in the reduction stamp (optional), provided if out-of-order
num_contrib in number of expected contributions from this node
Returns the pending send corresponding to the reduce

template<auto f, template<typename Arg> class Op = NoneOp, typename... Params>
PendingSendType vt::collective::reduce::Reduce::reduce(Node root, Params && ... params)

Perform a reduction without a message.

Parameters
root in the root node to target
params in parameters to reduce
Returns a pending send

template<typename MsgT, ActiveTypedFnType<MsgT>* f>
detail::ReduceStamp vt::collective::reduce::Reduce::reduceImmediate(NodeType root, MsgT*const msg, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType num_contrib = 1)

Reduce a message up the tree.

Parameters
root in the root node where the final handler provides the result
msg in the message to reduce on this node
id in the reduction stamp (optional), provided if out-of-order
num_contrib in number of expected contributions from this node
Returns the next reduction stamp

template<auto f>
detail::ReduceStamp vt::collective::reduce::Reduce::reduceImmediate(NodeType root, typename FuncTraits<decltype(f)>::MsgT*const msg, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType num_contrib = 1)

Reduce a message up the tree.

Parameters
root in the root node where the final handler provides the result
msg in the message to reduce on this node
id in the reduction stamp (optional), provided if out-of-order
num_contrib in number of expected contributions from this node
Returns the next reduction stamp

template<typename OpT, typename MsgT, ActiveTypedFnType<MsgT>* f>
PendingSendType vt::collective::reduce::Reduce::reduce(NodeType const& root, MsgT* msg, Callback<MsgT> cb, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType const& num_contrib = 1)

Reduce a message up the tree.

Parameters
root in the root node where the final handler provides the result
msg in the message to reduce on this node
cb in the callback to trigger on the root node
id in the reduction stamp (optional), provided if out-of-order
num_contrib in number of expected contributions from this node
Returns the next reduction stamp

template<typename OpT, auto f>
PendingSendType vt::collective::reduce::Reduce::reduce(NodeType const& root, typename FuncTraits<decltype(f)>::MsgT* msg, Callback<typename FuncTraits<decltype(f)>::MsgT> cb, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType const& num_contrib = 1)

Reduce a message up the tree.

Parameters
root in the root node where the final handler provides the result
msg in the message to reduce on this node
cb in the callback to trigger on the root node
id in the reduction stamp (optional), provided if out-of-order
num_contrib in number of expected contributions from this node
Returns the next reduction stamp

template<typename OpT, typename MsgT, ActiveTypedFnType<MsgT>* f>
detail::ReduceStamp vt::collective::reduce::Reduce::reduceImmediate(NodeType const& root, MsgT* msg, Callback<MsgT> cb, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType const& num_contrib = 1)

Reduce a message up the tree.

Parameters
root in the root node where the final handler provides the result
msg in the message to reduce on this node
cb in the callback to trigger on the root node
id in the reduction stamp (optional), provided if out-of-order
num_contrib in number of expected contributions from this node
Returns the next reduction stamp

template<typename OpT, auto f>
detail::ReduceStamp vt::collective::reduce::Reduce::reduceImmediate(NodeType const& root, typename FuncTraits<decltype(f)>::MsgT* msg, Callback<typename FuncTraits<decltype(f)>::MsgT> cb, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType const& num_contrib = 1)

Reduce a message up the tree.

Parameters
root in the root node where the final handler provides the result
msg in the message to reduce on this node
cb in the callback to trigger on the root node
id in the reduction stamp (optional), provided if out-of-order
num_contrib in number of expected contributions from this node
Returns the next reduction stamp

template<typename OpT, typename FunctorT, typename MsgT, ActiveTypedFnType<MsgT>* f>
PendingSendType vt::collective::reduce::Reduce::reduce(NodeType const& root, MsgT* msg, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType const& num_contrib = 1)

Reduce a message up the tree with a target function on the root node.

Parameters
root in the root node where the final handler provides the result
msg in the message to reduce on this node
id in the reduction stamp (optional), provided if out-of-order
num_contrib in number of expected contributions from this node
Returns the next reduction stamp

template<typename OpT, typename FunctorT, auto f>
PendingSendType vt::collective::reduce::Reduce::reduce(NodeType const& root, typename FuncTraits<decltype(f)>::MsgT* msg, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType const& num_contrib = 1)

Reduce a message up the tree with a target function on the root node.

Parameters
root in the root node where the final handler provides the result
msg in the message to reduce on this node
id in the reduction stamp (optional), provided if out-of-order
num_contrib in number of expected contributions from this node
Returns the next reduction stamp

template<typename OpT, typename FunctorT, typename MsgT, ActiveTypedFnType<MsgT>* f>
detail::ReduceStamp vt::collective::reduce::Reduce::reduceImmediate(NodeType const& root, MsgT* msg, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType const& num_contrib = 1)

Reduce a message up the tree with a target function on the root node.

Parameters
root in the root node where the final handler provides the result
msg in the message to reduce on this node
id in the reduction stamp (optional), provided if out-of-order
num_contrib in number of expected contributions from this node
Returns the next reduction stamp

template<typename OpT, typename FunctorT, auto f>
detail::ReduceStamp vt::collective::reduce::Reduce::reduceImmediate(NodeType const& root, typename FuncTraits<decltype(f)>::MsgT* msg, detail::ReduceStamp id = detail::ReduceStamp{}, ReduceNumType const& num_contrib = 1)

Reduce a message up the tree with a target function on the root node.

Parameters
root in the root node where the final handler provides the result
msg in the message to reduce on this node
id in the reduction stamp (optional), provided if out-of-order
num_contrib in number of expected contributions from this node
Returns the next reduction stamp

template<typename MsgT>
void vt::collective::reduce::Reduce::reduceAddMsg(MsgT* msg, bool const local, ReduceNumType num_contrib = -1)

Combine in a new message for a given reduction.

Parameters
msg in the message to combine with the operator
local in was this called locally or from an incoming handler
num_contrib in the number of expected local contributions

template<typename MsgT>
void vt::collective::reduce::Reduce::reduceNewMsg(MsgT* msg)

Combine and send up the tree if ready.

Parameters
msg in the message to reduce

template<typename MsgT>
void vt::collective::reduce::Reduce::startReduce(detail::ReduceStamp id, bool use_num_contrib = true)

Explicitly start the reduction when the number of contributions is not known up front.

Parameters
id in the reduce stamp to start
use_num_contrib in whether to use the cached # of contributions

template<typename MsgT>
void vt::collective::reduce::Reduce::reduceRootRecv(MsgT* msg)

Active function when a message reaches the root of the spanning tree and the reduction is complete.

Parameters
msg in the reduce message

template<typename MsgT>
void vt::collective::reduce::Reduce::reduceUpHan(MsgT* msg)

Active function when a message arrives for a given scope at some level in the spanning tree.

Parameters
msg in the reduce message