Message Destinations

Overview
Simulate workers can communicate with each other through the Message API. This is also how interaction events from clients are exposed to Simulate workers.
Messages are arbitrary binary data so it is the responsibility of the user to make messages self-describing in such as way that messages can be distinguished from one another.
In both cell and background workers, the message reader and writer types are exposed as reader_type and writer_type, respectively.
Message destinations
Messages in Simulate must have a specified destination. A destination can be a process or multiple processes (in case of a broadcast) or a topic, which represents a particular interest. Unlike messages addressed directly to processes, messages addressed to topics are only delivered to processes that have explicitly registered an interest in that topic.
Messages sent by clients are published to topics that represent an interest in the user ID of that client. In this way, we can ensure that interaction events sent from clients are only received by the Simulate process (or processes) that needs to see them.
The following destinations are possible, and are defined in the aether::message namespace unless otherwise specified. Each is a separate type:
​
Directed Messages
Directed messages allow users to send a message to a specific worker. They are typically used when responding to a request from another worker which was received via a broadcast
global_state
the global state process
worker_id
the type used elsewhere in Simulate to represent a worker ID. It is advised not to use worker IDs to address messages since the changing configuration of Simulate cells means that workers may be deallocated or resized in a way that makes delivery to that worker no longer useful.
Broadcast Messages
Broadcast style messages will be delivered to specific workers, however the workers selected will be determines by Simulate based on criteria defined in the destination.
all_workers
a broadcast to all workers in the simulation. Use of this should be avoided when possible due to the amount of message traffic it may generate.
inside_shape
passed a shape that can be either a circle, rectangle or trapezoid or their 3D equivalents, every worker that is managing an area covered by the shape described will receive the message 
closest_worker
this message will be sent to a single worker, Simulate will look to find the Cell Worker that is managing the region of space including the coordinates provided. It no worker is assigned to that region then the worker that is closest to the coordinate will be selected. closest_worker's constructor takes a single parameter which is the Cartesian coordinate of the destination.
Topics
A topic does not define an explicit destination rather, Simulate processes can choose to subscribe to topics they consider relevant, Aether defines a set of standard topics but is it also possible to create your own.
A topics are defined in the aether::message::topic namespace. They have the following constructors:
user_id(uint64_t)
entity_id(uint64_t)
custom(uint64_t)
unclaimed_events() (this type cannot be used as a destination and will be discussed later)
Grouping Topics
When sending messages you are actually creating a list of topics. 
A topic_list instance can be constructed via various constructors and static builder functions:
static topic_list topic_list::user_id(uint64_t user_id)
Builds a topic_list that represents interest in messages related to a specified user ID. Interaction messages received from clients are published to topics for the user ID they authenticated as.
static topic_list topic_list::entity_id(uint64_t entity_id)
Builds a topic_list that represents interest in messages related to a specific entity ID. These could be used to send messages to workers containing a specified entity.
static topic_list topic_list::custom_topic(uint64_t id)
Builds a topic_list that represent interest in messages related to a specific integer value. The meaning of this value is not defined by Simulate and can be used to implement custom topics.
topic_list::topic_list(const std::vector<publisher_topic_type> &)
topic_list::topic_list(std::vector<publisher_topic_type> &&)
topic_list::topic_list(std::initialization_list<publisher_topic_type>)
Builds a topic_list from a vector or brace initialisation list of publisher_topic_type which is a variant of the user_id, entity_id and custom topic types.
Last modified 5mo ago