System Messaging

Last updated on 16th July 2024

This is an experimental feature!

Experimental features are early versions for users to test before final release. We work hard to ensure that every available Simudyne SDK feature is thoroughly tested, but these experimental features may have minor bugs we still need to work on.

If you have any comments or find any bugs, please share with support@simudyne.com.

You have the possibility to apply certain modifications on an Agent before the beginning of a phase or after its end .

The SystemMessage is a new subtype of Message processed before the beginning of the Actions. You can use them to apply changes before the phase even begins.

The new method deferTask(Consumer< Vertex< ? extends Serializable>>) postpones the application of a modification after the end of the phase.

deferTask

The method deferTask is a member of the interface Environment, see its declaration below.

Declaration of deferTask() in Environment (Java)
public interface Environment<S extends Serializable> {
...
...

	void deferTask(Consumer<Vertex<S>> dataInjector);
}

You can call this method from an Agent, and use a lambda as argument. The lambda will be processed right after the Actions, at the end of the phase.

Example of use of deferTask() (Java)
deferTask(vertex -> vertex.getLinks().get(0).remove());

This will remove a Link of the Vertex at the end of the phase, but the Link would still exist and would still be available during this phase.

SystemMessage

SystemMessage is a Java Interface. It is used to define Messages that are processed automatically right at the beginning of the phase, before the Actions.

The SystemMessage Interface (Java)
public interface SystemMessage {
  boolean receivedByVertex(Agent<? extends GlobalState> agent, Environment<? extends GlobalState> env);
}

The only method you must implement is receivedByVertex. This method will be called by the Agent receiving the message. You must describe the modification you want to apply on the Agent receiving the message in this method (note that the argument agent represents the Agent receiving the message).

The method returns a boolean deciding whether or not the Agent will handle its Actions. If an Agent receives a SystemMessage with a receivedByVertex returning false, then its Actions will not be processed for this phase. If you do not wish to prevent the execution of the Actions, return true for all your receivedByVertex methods. Note that you only need one receivedByVertex returning false to prevent the Actions being processed, even if all the other receivedByVertex methods called by the Agent return true.

SystemMessages are used for lot of purposes
Be careful when using a SystemMessage , as some other functionalities are using this method. For instance, the PoisonPill feature is using SystemMessage. You should therefore be careful if you try to access data with a SystemMessage. Agents may be in an 'intermediate' state and not ready yet for Actions.
Example of custom SystemMessage (Java)
public static class MyMessage extends Message implements SystemMessage {
    public int field1;
    public int field2;

    @Override
    public boolean receivedByVertex(Agent<? extends GlobalState> agent, Environment<? extends GlobalState> env) {
      return true;
    }
  }
SystemMessages cannot begin a phase
A SystemMessage will not be put into the Agent's inbox. This allows you to send 'invisible' messages to an Agent, as the Agent will not react to it. For instance, you could send a SystemMessage to an `Agent` to update one of its fields, and do so without triggering a phase for this `Agent` (because his inbox would still be empty).