template<typename EntityID, typename Comm>
loc::Coordinator struct

Distributed location resolver for a set of migratable entities.

Template parameters
EntityID serializable, default-constructible, hashable entity id
Comm a communicator type satisfying loc::Communicator

A Coordinator answers the question "which rank currently hosts entity X" and keeps that answer coherent as entities migrate. It is a resolver only: it never forwards the entity's own messages. Once a location is resolved the embedder performs the actual send.

Each entity has a fixed home rank (a deterministic function of its id, chosen by the embedder). The home holds the authoritative record; other ranks cache resolutions and are refreshed eagerly when the location changes.

All inter-rank traffic goes through the injected Comm (any type satisfying loc::Communicator): the coordinator registers itself as a collective instance and issues point-to-point control messages via Comm::send<&method>. Because registration is collective, every rank must construct its coordinator in the same order so instance handles line up.

Constructors, destructors, conversion operators

Coordinator(Comm& in_comm, LocationSizeType in_max_cache_size = default_max_cache_size) explicit
Construct and collectively register with the communicator.

Public functions

void registerEntity(EntityID const& id, NodeType home)
Register an entity as living on this rank.
void entityImmigrated(EntityID const& id, NodeType home, NodeType from)
Register an entity that immigrated here from another rank.
void entityEmigrated(EntityID const& id, NodeType new_node)
Note that an entity has emigrated off this rank to new_node.
void unregisterEntity(EntityID const& id)
Unregister an entity that no longer lives here.
void getLocation(EntityID const& id, NodeType home, NodeAction action)
Resolve the current location of an entity.
void entityExists(EntityID const& id, NodeType home, ExistsAction action)
Check whether an entity exists anywhere in the system.
auto isCached(EntityID const& id) const -> bool
Whether a resolved location for id is held locally (local or cached).
void clearCache()
Drop all cached (non-home) resolutions.
auto thisNode() const -> NodeType
This rank.
void updateHome(EntityID id, NodeType node)
[home] Learn/refresh where an entity lives.
void locationRequest(EntityID id, NodeType requester)
[home] A rank asks where an entity lives.
void resolveResponse(EntityID id, NodeType node)
[asker] Home answered a location request.
void existsRequest(EntityID id, NodeType requester)
[home] A rank asks whether an entity exists.
void existsResponse(EntityID id, bool exists, NodeType node)
[asker] Home answered an existence request.

Function documentation

template<typename EntityID, typename Comm>
loc::Coordinator<EntityID, Comm>::Coordinator(Comm& in_comm, LocationSizeType in_max_cache_size = default_max_cache_size) explicit

Construct and collectively register with the communicator.

Parameters
in_comm in the communicator (must outlive this coordinator)
in_max_cache_size in max cached (non-home) location records

template<typename EntityID, typename Comm>
void loc::Coordinator<EntityID, Comm>::registerEntity(EntityID const& id, NodeType home)

Register an entity as living on this rank.

Parameters
id in the entity id
home in the home rank for id

template<typename EntityID, typename Comm>
void loc::Coordinator<EntityID, Comm>::entityImmigrated(EntityID const& id, NodeType home, NodeType from)

Register an entity that immigrated here from another rank.

Equivalent to registerEntity for resolution purposes: the entity now lives here and the home is informed.

template<typename EntityID, typename Comm>
void loc::Coordinator<EntityID, Comm>::entityEmigrated(EntityID const& id, NodeType new_node)

Note that an entity has emigrated off this rank to new_node.

The local record is repointed so local queries forward to the new node; the home is refreshed by the destination's entityImmigrated.

template<typename EntityID, typename Comm>
void loc::Coordinator<EntityID, Comm>::getLocation(EntityID const& id, NodeType home, NodeAction action)

Resolve the current location of an entity.

Parameters
id in the entity id
home in the home rank for id
action in callback invoked with the resolved node

action is invoked (possibly after communication with the home rank) with the resolved node. Progress requires the embedder to pump Comm::poll.

template<typename EntityID, typename Comm>
void loc::Coordinator<EntityID, Comm>::entityExists(EntityID const& id, NodeType home, ExistsAction action)

Check whether an entity exists anywhere in the system.

Parameters
id in the entity id
home in the home rank for id
action in callback invoked with (exists, node)