Fork me on GitHub

Event Reference

This document describes how to define events in SARL. Before reading this document, we recommend that you read the General Syntax Reference.

An event is one of the core concepts in SARL. It is a data structure composed of attributes where each attribute has a name, a type, and a value.

Events are exchanged among the agents or the behavioral units of agents, inside a given Space.

Each event has:

1. Event vs. Message

In computer-science literature, there are two main approaches for communicating between entities: (1) an event and (2) a message.

An event and a message are similar in that they each have a name (or type), a source, and optional data (arguments or parameters). The difference is in whether there is a receiver: an event does not specify a receiver, while a message needs to have at least one receiver (even if it is a group such as “all”
possible receivers).

Because the event approach is more general and close to the typical agent definitions in SARL, it is preferred by the designers of SARL.

So, to send data to another entity in SARL, you create an instance of an event and emit the event in a Space. The sending API is detailed in the Built-in Capacity Reference.

Note There is no message concept in SARL. All communication is done by using an Event.

2. Defining an Event

2.1. Define an empty event

An event is defined with the event keyword followed by the name of the event (without the qualified name of its package, which is inferred from the package keyword, if present).

When an event does not contain any additional data (so is “empty”), nothing further is required (though an empty block is allowed).

The example below contains the definition of Event1 and Event2, which are both empty. The first event is defined with the “empty block” syntax. The second event is defined with the “nothing” syntax.

event Event1 {  }
event Event2

2.2. Define an event with attributes

An Event may can carry additional information beyond its name (or type). This information is described by a set of attributes (or typed key/value pairs). Each attribute is declared according to the “Field Declaration” of the General Syntax Reference.

The following code example defines the event MyEvent with three attributes. Each declaration of the attributes illustrates one possible syntax for defining a field:

According to the type inference mechanism used by SARL, the attribute something will have the type Object.

Note Because of the use of the var keyword, the values of these attributes can be modified.

event MyEvent {
	var number : Integer
	var string = "abc"
	var something : Object
}

2.3. Define an event with value attributes

Events in SARL will carry data that is unmodifiable when an attribute is defined using the val keyword.

Important Note The val keyword has the same semantics as the final modifier in the Java language. It means that an element defined with val can be initialized only once. It also means that the element is read-only. But if the element is a reference to an object, then the referenced object is not read-only (only the initial reference is).

Because the val keyword defines a single-initialization variable, there should be a way to specify the initial value. The initial value can be specified at the end of the val directive or by specifying a constructor.

event MyEvent {
	val string = "abcd"
	val number : Integer
	
	new(nb : Integer) {
		number = nb
	}
}

If no constructor is defined in the event type and a super-type is declared, implicit constructors will be assumed. Implicit constructors has the same prototypes as the constructors of the super type. Details on implicit constructors are given in the reference documentation related to the synthetic functions.

2.4. Define an event with generic type parameter

Generics are a facility of generic programming that were added in several programming languages such as Java. They were designed to extend SARL type system to allow “a type or method to operate on objects of various types while providing compile-time type safety”.

A type parameter is an unqualified identifier. Type parameters are introduced by generic declarations, e.g. of events, classes, interfaces or actions/methods.

A event is generic if it declares one or more type parameters. A generic event declaration defines a set of parameterized types, one for each possible invocation of the type parameter section. All of these parameterized types share the same class at runtime.

Each type parameter is defined by:

To define the type parameters for an event, you should define them in a list between the characters lower-than < and upper-then >. In the following example, three type parameters are defined: T1, T2 and T3. The first type parameter T1 is defined without explicit bound, that means that all the values of T1 type must be a subtype of Object. The second type parameter T2 is defined to have all the values with a type being a subtype of String. The third type parameter T3 is defined to have all the values with a type being subtype of Double and Iterable<Character>. THe type parameters T1, T2 and T3 are used as regular types for the declarations of the fields value0, value1 and value2, respectively.

event MyEvent<T1, T2 extends String, T3 extends Double & Iterable<Character>> {
	var value0 : T1
	var value1 : T2
	var value2 : T3
}

2.5. Extending Events

In some use cases, it is useful to specialize the definition of an event. This mechanism is supported by the inheritance feature of SARL, which has the same semantic as the inheritance mechanism as the Java object-oriented language.

The extended event is specified just after the extends keyword.

Very Important Note An event type can extend only one other event type. This is similar to the model for class extensions in the Java language.

Declaration

In the following code, the first event is defined with the name Event1 and an attribute named string. A second event Event2, is defined as an extension of the first event. It contains a new attribute named number. It is now possible to create instances of these events. For Event1, only the attribute string is available. For Event2, two attributes are available (Event2 inherits one field from Event2 and defines one field).

event Event1 {
	var string : String
}
event Event2 extends Event1 {
	var number : int
}

Use

The following code illustrates the use of event instances.

// Create an instance of Event1 and set its attribute.
var e1 = new Event1
e1.string = "abc"
// Create an instance of Event2 and set its attributes.
var e2 = new Event2
e2.string = "abc"
e2.number = 345

2.6. Modifiers

Modifiers are used to modify declarations of types and type members. This section introduces the modifiers for the event. The modifiers are usually written before the keyword for defining the event.

The complete description of the modifiers’ semantic is available in this section.

Event Modifiers

An event may be declared with one or more modifiers, which affect its behavior:

Examples:

public event Example1 {
}
package event Example2 {
}
final event Example3 {
}

Field Modifiers

The modifiers for the fields in an event are:

Example:

public var example1 : Object

3. Reserved Events

Several events are defined and reserved by the SARL Core Specification. They describe the minimal set of events that a runtime environment must support to run a SARL program.

Very Important Note You must not define an event with a fully qualified name equals to one of the reserved events.

Two types of reserved events exist:

Copyright © 2014-2024 SARL.io, the Original Authors and Main Authors.

Documentation text and medias are licensed under the Creative Common CC-BY-SA-4.0; you may not use this file except in compliance with CC-BY-SA-4.0. You may obtain a copy of CC-BY-4.0.

Examples of SARL code are licensed under the Apache License, Version 2.0; you may not use this file except in compliance with the Apache License. You may obtain a copy of the Apache License.

You are free to reproduce the content of this page on copyleft websites such as Wikipedia.

Generated with the translator docs.generator 0.14.0.