Communication between agents

Agents living in one environment can communicate via sending messages to each other.

Agent functions for communication

Sending messages: send() /*recommended*/

Function	Description
void sendToAll(Object msg)	Sends a message to all agents in the same environment where this agent lives in. Parameters: msg - a message
void sendToRandom (Object msg)	Sends a message to a randomly chosen agent in the same environment this agent lives in. Parameters: msg - a message
void sendToAllConnected (Object msg)	Sends a message to all connected agents. Parameters: msg - a message
void sendToRandomConnected (Object msg)	Sends a message to a randomly chosen connected agent. Parameters: msg - a message
void sendToAllNeighbors (Object msg)	Sends a message to all neighbors. Available only if this agent lives in discrete space environment. Parameters: msg - a message
void sendToRandomNeighbor (Object msg)	Sends a message to a randomly chosen neighbor. Available only if this agent lives in discrete space environment. Parameters: msg - a message
void send(Object msg, Agent dest)	Sends a message to a given agent. Parameters: msg - a message dest - the destination agent
void send(Object msg, MessageDeliveryType mode)	Sends a message to an agent or a group of agents, as specified by the mode parameter. Parameters: msg - a message mode - specifies the message sending mode, one of the following: ALL - the message will be delivered to all agents in the environment ALL_CONNECTED - the message will be delivered to all connected agents RANDOM - the message will be delivered to one randomly chosen agent in the environment (including the message sender) RANDOM_CONNECTED - the message will be delivered to one randomly chosen connected agent, if any ALL_NEIGHBORS - (in discrete space only) the message will be delivered to all agents in the neighboring cells, subject to the current neighborhood model RANDOM_NEIGHBOR - (in discrete space only) the message will be delivered to one randomly chosen neighbor, subject to the current neighborhood model

Instant message delivery: deliver()

Function	Description
void deliverToAllAgentsInside (Object msg)	Immediately delivers a message to all agents in the environment. Parameters: msg - the message
void deliverToRandomAgentInside (Object msg)	Immediately delivers a message to a random agent in the environment, if there are any agents. Parameters: msg - the message
void deliverToAllConnected (Object msg)	Delivers a message to all connected agents. Parameters: msg - the message
void deliverToRandomConnected (Object msg)	Delivers a message to a randomly chosen connected agent. Parameters: msg - a message
void deliverToAllNeighbors (Object msg)	Delivers a message to all neighbors. Parameters: msg - the message
void deliverToRandomNeighbor (Object msg)	Delivers a message to a randomly chosen neighbor. Parameters: msg - a message
void deliver(Object msg, Agent dest)	Delivers a message to a given agent immediately during this method call. Parameters: msg - a message dest - the destination agent
void deliver(Object msg, MessageDeliveryType mode)	Delivers a message to an agent or a group of agents, as specified by the mode parameter immediately during this method call. Parameters: msg - the message mode - specifies the message sending mode, one of the following: ALL - the message will be delivered to all agents in the environment ALL_CONNECTED - the message will be delivered to all connected agents RANDOM - the message will be delivered to one randomly chosen agent in the environment (including the message sender) RANDOM_CONNECTED - the message will be delivered to one randomly chosen connected agent, if any ALL_NEIGHBORS - (in discrete space only) the message will be delivered to all agents in the neighboring cells, subject to the current neighborhood model RANDOM_NEIGHBOR - (in discrete space only) the message will be delivered to one randomly chosen neighbor, subject to the current neighborhood model

Example:

people(0).sendToRandom("Hi!");

send() vs. deliver()

The difference between send() and deliver() is the following: send() schedules the message delivery/reception in a separate event that will be executed after the current event in 0 time, while deliver() executes the delivery/reception directly inside its body. If the recipients may try to communicate other agents during incoming message handling, using deliver() may cause undesirable loops, and it is recommended to use send(). The mode parameter may have the following values:

ALL - the message will be delivered to all agents in the environment.

ALL_CONNECTED - the message will be delivered to all connected agents.

RANDOM - the message will be delivered to one randomly chosen agent in the environment (including the message sender).

RANDOM_CONNECTED - the message will be delivered to one randomly chosen connected agent, if any.

ALL_NEIGHBORS - (in discrete space only) the message will be delivered to all agents in the neighboring cells, subject to the current neighborhood model.

RANDOM_NEIGHBOR - (in discrete space only) the message will be delivered to one randomly chosen neighbor, subject to the current neighborhood model.

Reacting on the message reception

Every agent that lives in environment has visual non-removable element connections that stores links to the contacts of this agent and defines communication settings. On the graphical diagram, you can find it above the X-axis:

Here you can define the reaction of the agent-recipient on the message reception.

To define agent's reaction on message arrival

1. Open the diagram of the agent that receives messages.
2. Scroll the graphical diagram a bit up and click connections element.
3. Open the Communication section of the properties.
4. Type the reaction code in the On message received section. Use msg to access the received message and sender to access the sender agent. By default, the message is of the Object type. If necessary, you can specify the type of the message in the Message type control.

Once the message is delivered to a destination agent, its action code is executed, if defined.

If you need to forward messages to a statechart inside the agent, select the checkbox corresponding to the required statechart in the Forward message to table.