#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 ThisType = EntityLocationCoord<EntityID>
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::vector<NodeActionType>
using ExistsListType = std::vector<ExistsNodeActionType>
using PendingType = PendingLocationLookup<EntityID>
using PendingLocLookupsType = std::unordered_map<EntityID, ActionListType>
using PendingExistsLocType = std::unordered_map<EntityID, ExistsListType>
using ActionContainerType = std::unordered_map<LocEventID, PendingType>
using LocAsksType = std::unordered_map<EntityID, std::unordered_set<NodeType>>
template<typename MessageT>
using EntityMsgType = EntityMsg<EntityID, MessageT>

Constructors, destructors, conversion operators

EntityLocationCoord()
Construct a new location manager with defaults.
EntityLocationCoord(bool in_anytime_migration, bool in_keep_cache_updated, std::size_t in_max_cache_size = default_max_cache_size) explicit
Construct with parameters.
~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 startMigrations()
Tell the location manager that migrations are going to start.
void doneMigrations()
Indicate that migrations are complete.
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.
auto entityExistsLocal(EntityID const& id) const -> bool
Check if the entity exists locally on this rank.
void entityExists(EntityID const& id, NodeType const& home_node, ExistsNodeActionType const& action)
Check if an entity exists in the system.
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(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.
void setProxy(objgroup::proxy::Proxy<EntityLocationCoord<EntityID>> proxy)
Set the proxy for the objgroup.
auto getLocalEntities() const -> std::vector<EntityID>
Get local entities.
auto buildGlobalMap() -> std::unordered_map<EntityID, NodeType>
All-reduce the global map of entity location.

Typedef documentation

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

#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::vector<NodeActionType>

#include <src/vt/topos/location/location.h>
template<typename EntityID>
using vt::location::EntityLocationCoord<EntityID>::ExistsListType = std::vector<ExistsNodeActionType>

#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>::PendingExistsLocType = std::unordered_map<EntityID, ExistsListType>

#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>::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()

Construct a new location manager with defaults.

#include <src/vt/topos/location/location.h>
template<typename EntityID>
vt::location::EntityLocationCoord<EntityID>::EntityLocationCoord(bool in_anytime_migration, bool in_keep_cache_updated, std::size_t in_max_cache_size = default_max_cache_size) explicit

Construct with parameters.

Parameters
in_anytime_migration in whether anytime migration is allowed
in_keep_cache_updated in whether to keep the cache updated
in_max_cache_size in what the max cache size is

#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>::startMigrations()

Tell the location manager that migrations are going to start.

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

Indicate that migrations are complete.

#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>
bool vt::location::EntityLocationCoord<EntityID>::entityExistsLocal(EntityID const& id) const

Check if the entity exists locally on this rank.

Parameters
id in the entity ID
Returns whether it exists locally

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

Check if an entity exists in the system.

Parameters
id in the entity ID
home_node in the home node for id
action in the exists/node action

#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(EntityID const& id, NodeType const& resolved_node, NodeType const& home_node)

Update location.

Parameters
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>
void vt::location::EntityLocationCoord<EntityID>::setProxy(objgroup::proxy::Proxy<EntityLocationCoord<EntityID>> proxy)

Set the proxy for the objgroup.

Parameters
proxy in proxy to set

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

Get local entities.

Returns vector of local entities

#include <src/vt/topos/location/location.h>
template<typename EntityID>
std::unordered_map<EntityID, NodeType> vt::location::EntityLocationCoord<EntityID>::buildGlobalMap()

All-reduce the global map of entity location.

Returns the global map of locations