gmx::ObservablesReducerBuilder Class Reference

#include <gromacs/mdtypes/observablesreducer.h>

Description

Builder for ObservablesReducer.

Receives subscriptions from MD modules. Caller should call build() once all subscriptions have been received, and then not attempt any further subscriptions or builds. At that time, the builder may be destructed.

This builder will

• receive all subscriptions from MD modules, then
• build the communication buffer used by the subscribers,
• build the ObservablesReducer object that manages the lifetime of that buffer, and
• notify the subscribers via callback of the view of that buffer that is theirs to use and a further callback to require reduction of that buffer. See also the interaction diagram in the documentation for observablesreducer.h file.

Note that the builder callbacks do not follow the approach of MDModulesNotifier because that requires that the same value is passed to all recipients. Here a distinct value goes to each recipient, ie. a different view of the communication buffer.

In order to avoid circular build-time dependencies between the ObservablesReducer (and its builder) with the modules that use it, the latter can directly call methods on the former, supplying anonymous callbacks to be used by the former to contact the latter. CallbackAfterReduction and CallbackFromBuilder are of this type.

A callback type CallBackToRequireReduction is also used instead of a direct method call on ObservablesReducer to require reduction. This is implemented by calling a method on the Impl object of a ObservablesReducer. This extends the interface of ObservablesReducer in a way that is not directly visible. That complexity provides two benefits:

• only registered subscribers can require reduction (which helps ensure correctness by construction)
• the ObservablesReducer::Impl has a stable address from the heap allocation needed for std::unique_ptr to use in forming the callback to request reduction. Alternatives exist for the latter, but create requirements on the stability of the address of ObservablesReducer, and/or extra coordination to only pass that address to subscribers once it is stable.

It is the subscribers' responsibility to coordinate so that all subscribers on all ranks agree on the need to communicate, e.g. by orchestrating communication based on the current step number or a previous message.

Classes
class	Impl
	Impl class for ObservablesReducerBuilder. More...

Public Types
using	CallbackAfterReduction = std::function< void(Step)>
	Convenience type for the callback subscribers to provide when they require reduction.
using	CallbackToRequireReduction = std::function< ObservablesReducerStatus(ReductionRequirement)>
	Convenience type for the callback subscribers call to require reduction. More...
using	CallbackFromBuilder = std::function< void(CallbackToRequireReduction &&, ArrayRef< double >)>
	Convenience type for the callback from the builder to notify the subscribers of the callback they will own and later use to require reduction and the view of the communication buffer they will later use.

Public Member Functions
	ObservablesReducerBuilder ()
	Constructor.
	~ObservablesReducerBuilder ()
	Destructor.
	ObservablesReducerBuilder (ObservablesReducerBuilder &&other) noexcept
	Move constructor.
ObservablesReducerBuilder &	operator= (ObservablesReducerBuilder &&other) noexcept
	Move assignment operator.
void	addSubscriber (int sizeRequired, CallbackFromBuilder &&callbackFromBuilder, CallbackAfterReduction &&callbackAfterReduction)
	Add a subscriber to the ObservablesReducer that will later be built in build() More...
ObservablesReducer	build ()
	Build a ObservablesReducer to which any subscribers have been added. More...

Member Typedef Documentation

using gmx::ObservablesReducerBuilder::CallbackToRequireReduction = std::function<ObservablesReducerStatus(ReductionRequirement)>

Convenience type for the callback subscribers call to require reduction.

When called, the status it returns can be used for checking the internal expectations of the subscriber on whether reduction has already occurred this step, or not.

Member Function Documentation

void gmx::ObservablesReducerBuilder::addSubscriber	(	int	sizeRequired,
		CallbackFromBuilder &&	callbackFromBuilder,
		CallbackAfterReduction &&	callbackAfterReduction
	)

Add a subscriber to the ObservablesReducer that will later be built in build()

Takes ownership of both callbacks supplied by the subscribing module. This approach ensures that time is not spent in the MD loop constructing std::function objects, because constructing one of those requires 1-2 heap allocations (depending on the size of the lambda capture).

Must not be called after build()

ObservablesReducer gmx::ObservablesReducerBuilder::build

(

)

Build a ObservablesReducer to which any subscribers have been added.

Must be called only once. Notifies each subscriber (via the CallbackFromBuilder that it supplied) of the view of the reduction buffer that they will use and the CallbackToRequireReduction that they will use.

---

The documentation for this class was generated from the following files:

• src/gromacs/mdtypes/observablesreducer.h
• src/gromacs/mdtypes/observablesreducer.cpp