#include <src/vt/topos/location/location.fwd.h>
template<typename EntityID>
vt::location::EntityLocationCoord struct

Part of a core VT component that manages the distributed location of virtual entities.

Allows general registration of an EntityID that is tracked across the system as it migrates. Routes messages to the appropriate node by inheriting from EntityMsg and sending it through the routing algorithm. Manages a distributed table of entities and their location allowing an entity to be found anywhere in the system. Caches locations to speed up resolution once a location is known. Allows migration of an entity at any time; forwards messages if they miss in the cache.

The registerEntity method allows an external component to locally register an entity as existing on this node. If the entity is deleted, unregisterEntity should be called; if the entity is migrated, entityEmigrated should be invoked on the node from which the entity is emigrating. A message may arrive for the entity by a location coordinator calling routeMsg to the associated entity.

Base classes

struct LocationCoord

Public types

using LocRecType = LocRecord<EntityID>
using LocCacheType = LocLookup<EntityID, LocRecType>
using LocEntityMsg = LocEntity<EntityID>
using LocalRegisteredContType = std::unordered_set<EntityID>
using LocalRegisteredMsgContType = std::unordered_map<EntityID, LocEntityMsg>
using ActionListType = std::list<NodeActionType>
using PendingType = PendingLocationLookup<EntityID>
using PendingLocLookupsType = std::unordered_map<EntityID, ActionListType>
using ActionContainerType = std::unordered_map<LocEventID, PendingType>
using LocMsgType = LocationMsg<EntityID>
using LocAsksType = std::unordered_map<EntityID, std::unordered_set<NodeType>>
template<typename MessageT>
using EntityMsgType = EntityMsg<EntityID, MessageT>

Constructors, destructors, conversion operators

EntityLocationCoord()
System call to construct a new entity coordinator.
EntityLocationCoord(collection_lm_tag_t, LocInstType identifier)
System call to construct a new entity coordinator for collections.
EntityLocationCoord(LocInstType const identifier) explicit
System call to construct a new entity coordinator.
~EntityLocationCoord() virtual

Public functions

void registerEntity(EntityID const& id, NodeType const& home, LocMsgActionType msg_action = nullptr, bool const& migrated = false)
Register a new entity.
void registerEntityRemote(EntityID const& id, NodeType const& home, NodeType const create_node, LocMsgActionType msg_action = nullptr)
Register a new entity that has been created remotely—on another rank off the home node.
void unregisterEntity(EntityID const& id)
Unregister an entity.
void entityEmigrated(EntityID const& id, NodeType const& new_node)
Tell coordinator that the entity has migrated to another node.
void entityImmigrated(EntityID const& id, NodeType const& home_node, NodeType const&__attribute__((unused)) from_node, LocMsgActionType msg_action = nullptr)
Register a migrated entity on new node.
void getLocation(EntityID const& id, NodeType const& home_node, NodeActionType const& action)
Get the location of an entity.
template<typename MessageT, ActiveTypedFnType<MessageT>* f>
void setupMessageForRouting(EntityID const& id, NodeType const& home_node, MsgSharedPtr<MessageT> const& msg)
template<typename MessageT, ActiveTypedFnType<MessageT>* f>
void routeMsgHandler(EntityID const& id, NodeType const& home_node, MsgSharedPtr<MessageT> const& msg)
Route a message with a custom handler.
template<typename MessageT>
void routePreparedMsgHandler(MsgSharedPtr<MessageT> const& msg)
Route a message with a custom handler.
template<typename MessageT>
void routePreparedMsg(MsgSharedPtr<MessageT> const& msg)
Route a message with a custom handler.
template<typename MessageT>
void routeMsgHandlerLocal(MsgSharedPtr<MessageT> const& msg)
Route a message with a custom handler where the element is local.
template<typename MessageT>
void routeMsg(EntityID const& id, NodeType const& home_node, MsgSharedPtr<MessageT> const& msg, NodeType from_node = uninitialized_destination)
Route a message to the default handler.
void routeNonEagerAction(EntityID const& id, NodeType const& home_node, ActionNodeType action)
Route a message with non-eager protocol.
void updatePendingRequest(LocEventID const& event_id, EntityID const& id, NodeType const& resolved_node, NodeType const& home_node)
Update location.
void printCurrentCache() const
Output the current cache state.
auto isCached(EntityID const& id) const -> bool
Check if the purported location of an entity is cached.
void clearCache()
Clear the cache.
void sendEagerUpdate(EntityID const& id, NodeType ask_node, NodeType home_node, NodeType deliver_node)
Send back an eager update on a discovered location.
void handleEagerUpdate(EntityID const& id, NodeType home_node, NodeType deliver_node)
Update cache on eager update received.
template<typename MessageT>
auto useEagerProtocol(MsgSharedPtr<MessageT> const& msg) const -> bool
Check if the eager or rendezvous protocol should be used.
auto getInst() const -> LocInstType
Get the instance identifier for this location manager.

Typedef documentation

#include <src/vt/topos/location/location.h>
template<typename EntityID>
using vt::location::EntityLocationCoord<EntityID>::LocRecType = LocRecord<EntityID>

#include <src/vt/topos/location/location.h>
template<typename EntityID>
using vt::location::EntityLocationCoord<EntityID>::LocCacheType = LocLookup<EntityID, LocRecType>

#include <src/vt/topos/location/location.h>
template<typename EntityID>
using vt::location::EntityLocationCoord<EntityID>::LocEntityMsg = LocEntity<EntityID>

#include <src/vt/topos/location/location.h>
template<typename EntityID>
using vt::location::EntityLocationCoord<EntityID>::LocalRegisteredContType = std::unordered_set<EntityID>

#include <src/vt/topos/location/location.h>
template<typename EntityID>
using vt::location::EntityLocationCoord<EntityID>::LocalRegisteredMsgContType = std::unordered_map<EntityID, LocEntityMsg>

#include <src/vt/topos/location/location.h>
template<typename EntityID>
using vt::location::EntityLocationCoord<EntityID>::ActionListType = std::list<NodeActionType>

#include <src/vt/topos/location/location.h>
template<typename EntityID>
using vt::location::EntityLocationCoord<EntityID>::PendingType = PendingLocationLookup<EntityID>

#include <src/vt/topos/location/location.h>
template<typename EntityID>
using vt::location::EntityLocationCoord<EntityID>::PendingLocLookupsType = std::unordered_map<EntityID, ActionListType>

#include <src/vt/topos/location/location.h>
template<typename EntityID>
using vt::location::EntityLocationCoord<EntityID>::ActionContainerType = std::unordered_map<LocEventID, PendingType>

#include <src/vt/topos/location/location.h>
template<typename EntityID>
using vt::location::EntityLocationCoord<EntityID>::LocMsgType = LocationMsg<EntityID>

#include <src/vt/topos/location/location.h>
template<typename EntityID>
using vt::location::EntityLocationCoord<EntityID>::LocAsksType = std::unordered_map<EntityID, std::unordered_set<NodeType>>

#include <src/vt/topos/location/location.h>
template<typename EntityID> template<typename MessageT>
using vt::location::EntityLocationCoord<EntityID>::EntityMsgType = EntityMsg<EntityID, MessageT>

Function documentation

#include <src/vt/topos/location/location.h>
template<typename EntityID>
vt::location::EntityLocationCoord<EntityID>::EntityLocationCoord()

System call to construct a new entity coordinator.

#include <src/vt/topos/location/location.h>
template<typename EntityID>
vt::location::EntityLocationCoord<EntityID>::EntityLocationCoord(collection_lm_tag_t, LocInstType identifier)

System call to construct a new entity coordinator for collections.

Parameters
identifier in the entity class identifier

#include <src/vt/topos/location/location.h>
template<typename EntityID>
vt::location::EntityLocationCoord<EntityID>::EntityLocationCoord(LocInstType const identifier) explicit

System call to construct a new entity coordinator.

Parameters
identifier in the entity class identifier

#include <src/vt/topos/location/location.h>
template<typename EntityID>
vt::location::EntityLocationCoord<EntityID>::~EntityLocationCoord() virtual

#include <src/vt/topos/location/location.h>
template<typename EntityID>
void vt::location::EntityLocationCoord<EntityID>::registerEntity(EntityID const& id, NodeType const& home, LocMsgActionType msg_action = nullptr, bool const& migrated = false)

Register a new entity.

Parameters
id in the entity ID
home in the home node for this entity
msg_action in function to trigger when message arrives for it
migrated in whether it migrated in: entityEmigrated is preferred

#include <src/vt/topos/location/location.h>
template<typename EntityID>
void vt::location::EntityLocationCoord<EntityID>::registerEntityRemote(EntityID const& id, NodeType const& home, NodeType const create_node, LocMsgActionType msg_action = nullptr)

Register a new entity that has been created remotely—on another rank off the home node.

Parameters
id in the entity ID
home in the home node for this entity
create_node in the node where the creation is occurring
msg_action in function to trigger when message arrives for it

#include <src/vt/topos/location/location.h>
template<typename EntityID>
void vt::location::EntityLocationCoord<EntityID>::unregisterEntity(EntityID const& id)

Unregister an entity.

Parameters
id in the entity ID

#include <src/vt/topos/location/location.h>
template<typename EntityID>
void vt::location::EntityLocationCoord<EntityID>::entityEmigrated(EntityID const& id, NodeType const& new_node)

Tell coordinator that the entity has migrated to another node.

Parameters
id in the entity ID
new_node in the node it was migrated to

#include <src/vt/topos/location/location.h>
template<typename EntityID>
void vt::location::EntityLocationCoord<EntityID>::entityImmigrated(EntityID const& id, NodeType const& home_node, NodeType const&__attribute__((unused)) from_node, LocMsgActionType msg_action = nullptr)

Register a migrated entity on new node.

Parameters
id in the entity ID
home_node in the home node for the entity
from_node
msg_action in function to trigger when message arrives for it

This should be called after the entity is migrated when it arrived on the new node: order of operations:

1) Node 0: registerEntity(my_id, ...); 2) Node 0: entityEmigrated(my_id, 1); 3) Node 1: entityImmigrated(my_id, <home>, 0, ...);

#include <src/vt/topos/location/location.h>
template<typename EntityID>
void vt::location::EntityLocationCoord<EntityID>::getLocation(EntityID const& id, NodeType const& home_node, NodeActionType const& action)

Get the location of an entity.

Parameters
id in the entity ID
home_node in the home node for the entity
action in the action to trigger with the discovered location

Get the location of a entity: the ‘action’ is triggered when the location of the entity is resolved. This is an asynchronous call that may send messages to discover the location of the entity ‘id’. To resolve the location the method uses the following algorithm:

1) Check locally for the entity's existence 2) If not local, search for a cache entry with location info 3) If no cache information available, send resolution message to home node. a) The home node applies the same algorithm, starting with (1) b) On step 3, if no information is known, the manager buffers the request, waiting to the entity to be registered in the future.

#include <src/vt/topos/location/location.h>
template<typename EntityID> template<typename MessageT, ActiveTypedFnType<MessageT>* f>
void vt::location::EntityLocationCoord<EntityID>::setupMessageForRouting(EntityID const& id, NodeType const& home_node, MsgSharedPtr<MessageT> const& msg)

#include <src/vt/topos/location/location.h>
template<typename EntityID> template<typename MessageT, ActiveTypedFnType<MessageT>* f>
void vt::location::EntityLocationCoord<EntityID>::routeMsgHandler(EntityID const& id, NodeType const& home_node, MsgSharedPtr<MessageT> const& msg)

Route a message with a custom handler.

Parameters
id in the entity ID
home_node in home node for entity
msg

#include <src/vt/topos/location/location.h>
template<typename EntityID> template<typename MessageT>
void vt::location::EntityLocationCoord<EntityID>::routePreparedMsgHandler(MsgSharedPtr<MessageT> const& msg)

Route a message with a custom handler.

#include <src/vt/topos/location/location.h>
template<typename EntityID> template<typename MessageT>
void vt::location::EntityLocationCoord<EntityID>::routePreparedMsg(MsgSharedPtr<MessageT> const& msg)

Route a message with a custom handler.

#include <src/vt/topos/location/location.h>
template<typename EntityID> template<typename MessageT>
void vt::location::EntityLocationCoord<EntityID>::routeMsgHandlerLocal(MsgSharedPtr<MessageT> const& msg)

Route a message with a custom handler where the element is local.

#include <src/vt/topos/location/location.h>
template<typename EntityID> template<typename MessageT>
void vt::location::EntityLocationCoord<EntityID>::routeMsg(EntityID const& id, NodeType const& home_node, MsgSharedPtr<MessageT> const& msg, NodeType from_node = uninitialized_destination)

Route a message to the default handler.

Parameters
id in the entity ID
home_node in home node for the entity
msg in pointer to the message
from_node in the sending node (optional)

#include <src/vt/topos/location/location.h>
template<typename EntityID>
void vt::location::EntityLocationCoord<EntityID>::routeNonEagerAction(EntityID const& id, NodeType const& home_node, ActionNodeType action)

Route a message with non-eager protocol.

Parameters
id in the entity ID
home_node in home node for the entity
action in action once entity is found

#include <src/vt/topos/location/location.h>
template<typename EntityID>
void vt::location::EntityLocationCoord<EntityID>::updatePendingRequest(LocEventID const& event_id, EntityID const& id, NodeType const& resolved_node, NodeType const& home_node)

Update location.

Parameters
event_id in the event ID waiting on the location
id in the entity ID
resolved_node in the node reported to have the entity
home_node in the home node for the entity

#include <src/vt/topos/location/location.h>
template<typename EntityID>
void vt::location::EntityLocationCoord<EntityID>::printCurrentCache() const

Output the current cache state.

#include <src/vt/topos/location/location.h>
template<typename EntityID>
bool vt::location::EntityLocationCoord<EntityID>::isCached(EntityID const& id) const

Check if the purported location of an entity is cached.

Parameters
id in the entity ID
Returns whether it is cached

#include <src/vt/topos/location/location.h>
template<typename EntityID>
void vt::location::EntityLocationCoord<EntityID>::clearCache()

Clear the cache.

#include <src/vt/topos/location/location.h>
template<typename EntityID>
void vt::location::EntityLocationCoord<EntityID>::sendEagerUpdate(EntityID const& id, NodeType ask_node, NodeType home_node, NodeType deliver_node)

Send back an eager update on a discovered location.

Parameters
id in the entity ID
ask_node in the asking node
home_node in the home node
deliver_node in the node discovered which delivered the message

#include <src/vt/topos/location/location.h>
template<typename EntityID>
void vt::location::EntityLocationCoord<EntityID>::handleEagerUpdate(EntityID const& id, NodeType home_node, NodeType deliver_node)

Update cache on eager update received.

Parameters
id in the entity ID
home_node in the home node
deliver_node in the node discovered which delivered the message

#include <src/vt/topos/location/location.h>
template<typename EntityID> template<typename MessageT>
bool vt::location::EntityLocationCoord<EntityID>::useEagerProtocol(MsgSharedPtr<MessageT> const& msg) const

Check if the eager or rendezvous protocol should be used.

Parameters
msg in the message to check
Returns whether it is of eager size

\internalThe eager protocol, typically used for small messages, forwards the message even if the location is stale or unknown (to the home node). The rendezvous protocol, typically used for large messages, will send a control message to determine the location of the entity before sending the actual data. The threshold between these two modes is controlled by small_msg_max_size

#include <src/vt/topos/location/location.h>
template<typename EntityID>
LocInstType vt::location::EntityLocationCoord<EntityID>::getInst() const

Get the instance identifier for this location manager.

Returns the instance ID