Communication between agents

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

Agent functions for communication

You send the messages by calling one of the listed functions.

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.

Having done this, you enable message processing by the statechart. If there are some active transitions that are triggered by the message reception, they will occur (if the received message satisfies the optional filters defined in the transition properties).