ReactiveMachine

Introduction
ReactiveMachine Design
Reactive community, Reactive Entity and Agent
Instant and synchronization
Event and Message
ReactiveMachine
Community Board and Action
Trace system
What has changed since version 2.0
What has changed since version 2.1
Packages
Examples of Board
Exit Board
DOM-like Board
Modify an Element
Constraints on children elements
Saving and restoring an ElementBoard
Packages
Demonstration
Conduct a test
Stop/Suspend
Syracuse
Event Order
Battle
Pass ball
Market
Land
Packages
Installation

Introduction

ReactiveMachine is a java-written reactive framework. It implements agents, which interact in a deterministic way, by using the reactive paradigm.

The purpose of this document is to describe origins, design and use of the ReactiveMachine software. In order to get a good understanding of it, you should be familiar with object-oriented programming and Java.

With its version 2.1 ReactiveMachine comes with a full test set. Any return of your experience on this product would be appreciated.

Software version2.1
Documentation version2.1

ReactiveMachine has mainly been inspired by publications around the Inria Mimosa project on reactive programming and more particularly on the Fair Threads framework. Like Fair Threads, ReactiveMachine installs a synchronization system between threads: the ReactiveMachine community corresponds to the Fair Threads scheduler. Unlike Fair Threads, ReactiveMachine is not deterministic about thread execution order.

ReactiveMachine Design

Reactive Community, Reactive Entity and Agent

At the centre of the ReactiveMachine is the ReactiveCommunity. A ReactiveCommunity accepts the connection of ReactiveEntities. Together, a ReactiveCommunity and its connected ReactiveEntities assume the reactive paradigm.

Each ReactiveEntity is associated to a Java thread, which gives life to an Agent. Application programming takes place through agents. An Agent is a java object overriding AgentImpl, which applies the reactive paradigm by using the primitives offered by its associated reactive entity. An Agent also has access to some primitives offered by the reactive community to which it is connected.

Life time of an Agent is composed of three phases: initialization, participation and termination. During initialization the Agent receives context information, during participation it expresses its own behavior and during termination it closes what is necessary.

At a given time, through its entity, an Agent is either connected or not connected to a community. It cannot be connected to more than one community. For connecting or disconnecting itself, an Agent uses respectively the connect() or disconnect() method of its entity.

From version 2.0 of the ReactiveMachine, a ReactiveCommunity is no more associated to a thread. It becomes a simple synchronization object.

ConceptContractImplementation
ReactiveCommunity
org.xmloperator.reactive.
ReactiveCommunity
org.xmloperator.reactive.impl.
ReactiveCommunityImpl
ReactiveEntity
org.xmloperator.reactive.
ReactiveEntity
org.xmloperator.reactive.impl.
ReactiveEntityImpl
Agent
org.xmloperator.reactive.
Agent
org.xmloperator.reactive.agent.
AgentImpl

Instant and synchronization

A community defines instants. An instant is identified by a long value. Activity of connected entities occurs during instants. An instant can end only when all connected entities have agreed to that. A community that makes the observation of the end of an instant can begin a new one (by incrementing its long value).

Since an instant is lived fully or not, entity connections and disconnections always occur during the end-of-instant, which is a dead time between successive instants.

An Agent declares to stop its activity for the current instant without condition by calling the stop() method of its entity. The call return will occur at the beginning of the next instant.

An Agent declares to suspend its activity for the current instant by calling the suspend() method of its entity. If all the other connected agents do the same then the call returns null at the beginning of the next instant. In contrast, if an elementary Event (see next section) is broadcasted during this instant then the method returns this broadcasted event during the same instant.

Thus the agents connected to a community have two ways to synchronize:

An instant can contain any number of suspensions.

Event and Message

Events support reactive communication between agents connected to a community. An Event is created by a community (at the request of an Agent) and belongs to this community. Any connected Agent can generate any event of its community.

There is two types of Event:

The type of an Event is decided in its creation.

An Event is or is not generated during a given instant. This is the reason why an elementary Event can be immediately broadcasted. Another Agent (or the same) is allowed to generate the same elementary Event during the same instant but with no effect.

A Message Event cannot be broadcasted during the instant of generation because another Agent can generate the same Message Event with another Message, which will be lost since event broadcasting already occurs during the instant. Broadcasting of a Message Event is differed to the beginning of the next instant. A Message Event is broadcasted with all the messages coming with it.

A Message Event can be exclusively attached to one entity. In this case, the corresponding Agent will be the only one to receive the Event. This allows an agent to agent communication much more efficient.

There is no exclusive elementary Event. An elementary Event is always broadcasted to the whole community.

A Message is sender certified: a recipient Agent can take note of the entity identifier of the sender.

A ReactiveAgent is an Agent that acts in a standart way in response to solicitations. A developer who uses this artifact doesn't worry any more about suspensions.

ConceptContractImplementation
Event
org.xmloperator.reactive.
Event
org.xmloperator.reactive.impl.
EventImpl
Message
org.xmloperator.reactive.
Message
org.xmloperator.reactive.impl.
MessageImpl
ReactiveAgent
org.xmloperator.reactive.
ReactiveAgent
org.xmloperator.reactive.agent.
ReactiveAgentImpl

Warning: the term "Message" has changed meaning in version 2.0. In version 1.0, it pointed to the Message Event.

ReactiveMachine

The object that is responsible of creating communities and launching agents is the ReactiveMachine. The ReactiveMachine is unique within the Java virtual machine. A reference to a ReactiveMachine is obtained through a ReactiveFactory.

At launching, an Agent receives a LaunchingContext. it contains reference to:

ConceptContractImplementation
ReactiveMachine
org.xmloperator.reactive.
ReactiveMachine
org.xmloperator.reactive.agent.
ReactiveMachineImpl
ReactiveFactory
org.xmloperator.reactive.
ReactiveFactory
org.xmloperator.reactive.agent.
ReactiveFactoryImpl
LaunchingContext
org.xmloperator.reactive.
LaunchingContext
org.xmloperator.reactive.agent.
LaunchingContextImpl

Community Board and Action

Often multiple agents may need to store the same information. It is thus tempting to share this information but it must be done without affecting the determinism. This is realized by the community Board, whose data can change only during end-of-instants.

For making the board (or any other environment of the community) data change during end-of-instants, actions are used. An Action is generated by an Agent, either directly or using an ActionMessage. The Action is executed during the end-of-instant, while the ActionMessage (if any) is broadcasted at the beginning of the next instant, as every Message.

Reversing an Action is not proposed because usually not deterministic.

ConceptContractImplementation
Action
org.xmloperator.reactive.
Action
org.xmloperator.reactive.impl.
ActionImpl
ActionMessage
org.xmloperator.reactive.
ActionMessage
org.xmloperator.reactive.impl.
ActionMessageImpl
Board
org.xmloperator.reactive.Board
org.xmloperator.reactive.impl.
BoardImpl

Trace system

A trace system is avalaible for debugging. It is activated by calling the setTrace() method of ReactiveFactoryImpl. Trace activation operates at the class level: if traces are on for a class then all the instances of this class will generate traces.

The classes that propose traces are the following:

Following are examples of traces:

TraceComments
A2 is [..]SyracuseAgent/13
Agent number 2 is launched.
C1.2 A3 suspend
Within Community 1, during instant 2, Agent 3 suspends.
C1.2 A3 generates E4
Within Community 1, during instant 2, Agent 3 generates Event 4.
C1.2 A3 generates ME5 A3("Hello")
Within Community 1, during instant 2, Agent 3 generates the MessageEvent 5 with the Message "Hello".
ReactiveMachine is done
All agents are done.

What has changed since version 2.0

Particular attention was paid to make the ReactiveMachine simpler and more focused on its function. All that appeared unnecessary or overly complex was eliminated.

About ReactiveCommunity :

About events and messages :

About actions :

About agents :

What has changed since version 2.1

ReactiveMachine was made usable in larger contexts. Tests has been extended. Determinism keeps main attention.

About events and messages :

About actions :

About agents :

Packages

Your application program should include (at least) the following java packages :

-----------------
Dependent_package
Used_package
-----------------
org.xmloperator.reactive.exception
org.xmloperator.reactive
org.xmloperator.reactive.exception
org.xmloperator.reactive.impl
org.xmloperator.reactive.exception
org.xmloperator.reactive
org.xmloperator.reactive.agent
org.xmloperator.reactive.exception
org.xmloperator.reactive
org.xmloperator.reactive.impl

Examples of Board

Exit Board

This board implementation is as simple as possible. Its role is to invite all the agents to either continue or terminate. An Agent that wants to invite the others to terminate has to generate an ExitAction. The execution of ExitAction during the end-of-instant has the effect of calling the terminate() method of the ExitBoard.

ConceptImplementation
ExitAction
org.xmloperator.reactive.demo.syracuse.
ExitAction
ExitBoard
org.xmloperator.reactive.demo.syracuse.
ExitBoard

DOM-like Board

This board implementation is pretty generic (but complex). This is a hierarchical structure of elements that looks very like the Document Object Model (DOM) of the W3C. An advantage of such a data structure is that it can be easily read or written as an XML content.

An Element is either a ParentElement, a DataElement or an empty element. A ParentElement can have children elements, a DataElement cannot, neither an empty one. Any Element has a local name and, possibly, a namespace URI.

A DataElement is a recipient for a data with a given data type, which corresponds to a Java type. Used data types are: long, double, string and object. An object data type corresponds to a TranslatableObject. A TranslatableObject is an Object with a method for translating it to an Element and another method that is used for instantiating an Object, called Rebuilder, which is able to rebuild the TranslatableObject from its representing Element.

Conformant to the board contract, all element attributes are readable (by any agent) but none are (directly) writable. TranslatableObjects have to conform to the same contract.

ConceptContractImplementation
Element
org.xmloperator.reactive.element.
Element
org.xmloperator.reactive.element.impl.
ElementImpl
ParentElement
org.xmloperator.reactive.element.
ParentElement
org.xmloperator.reactive.element.impl.
ParentElementImpl
DataElement
org.xmloperator.reactive.element.
DataElement
org.xmloperator.reactive.element.impl.
[Long|Double|String|Object]DataElementImpl
TranslatableObject
org.xmloperator.reactive.element.
TranslatableObject
Rebuilder
org.xmloperator.reactive.element.
Rebuilder

Modify an Element

In order to modify an Element (during an end-of-instant) the board uses a RWElement. Any access to this RWElement requires a key that only the board has.

ConceptContractImplementation
RWElement
org.xmloperator.reactive.element.RWElement
org.xmloperator.reactive.element.impl.
RWElementImpl

The following Actions on Element are available:

ActionDescriptionImplementation
InsertA given element is inserted before a reference Element.
org.xmloperator.reactive.element.action.
ElementInsertAction
AppendA given Element is appended as last child of a reference ParentElement.
org.xmloperator.reactive.element.action.
ElementAppendAction
RemoveA reference Element is removed.
org.xmloperator.reactive.element.action.
ElementRemoveAction
ChildrenRemoveThe children of a reference ParentElement are removed.
org.xmloperator.reactive.element.action.
ChildrenRemoveAction
ChildrenSortThe children of a reference ParentElement are sorted using a Comparator of Element.
org.xmloperator.reactive.element.action.
ChildrenSortAction
Remarks
  • Setting the data of a DataElement is not proposed because not deterministic.
  • Removing an already removed Element does nothing, what ever be the instant.
  • Element order obtained by Insert and/or Append is not deterministic. For a given order of children elements, use ChildrenSort.

Constraints on children elements

Constraints can be set on the children elements of a ParentElement. The following ChildrenConstraints are available:

ConstraintDescriptionImplementation
DifferentNamesTwo children elements of a ParentElement cannot have the same name (local name and namespace URI).
org.xmloperator.reactive.element.constraint.
DifferentNamesChildrenConstraint
FixedNameAll the children elements of a ParentElement have the same given name (local name and namespace URI).
org.xmloperator.reactive.element.constraint.
FixedNameChildrenConstraint
ChildCountThe count of the children elements of a ParentElement cannot be less than a min value after a remove operation neither greater than a max value (-1 for no max value) after an insert/append operation.
org.xmloperator.reactive.element.constraint.
ChildCountChildrenConstraint

An ElementAction whose execution is contrary to a ChildrenConstraint returns a ChildrenConstraintException in the ActionMessage.

ConceptContract
ChildrenConstraint
org.xmloperator.reactive.element.ChildrenConstraint

Saving and restoring an ElementBoard

The ElementBoard provides access to the RootElement, which is a ParentElement. Namespaces are handeld at RootElement level.

ConceptContractImplementation
ElementBoard
org.xmloperator.reactive.element.
ElementBoard
org.xmloperator.reactive.element.impl.
ElementBoardImpl
RootElement
org.xmloperator.reactive.element.
RootElement
org.xmloperator.reactive.element.impl.
RootElementImpl

Saving and restoring a RootElement are respectively assumed by the DocumentWriter and DocumentReader objects.

ObjectImplementation
DocumentWriter
org.xmloperator.reactive.element.util.
DocumentWriter
DocumentReader
org.xmloperator.reactive.element.util.
DocumentReader

Packages

The DOM-like Element Board uses the following java packages :

-----------------
Dependent_package
Used_package
-----------------
org.xmloperator.reactive.element.exception
org.xmloperator.reactive.element
org.xmloperator.reactive.exception
org.xmloperator.reactive.element.exception
org.xmloperator.reactive.element.impl
org.xmloperator.reactive.exception
org.xmloperator.reactive.impl
org.xmloperator.reactive.element.exception
org.xmloperator.reactive.element
org.xmloperator.reactive.element.constraint
org.xmloperator.reactive.element.exception
org.xmloperator.reactive.element
org.xmloperator.reactive.element.action
org.xmloperator.reactive.impl
org.xmloperator.reactive.element
org.xmloperator.reactive.element.util
org.xmloperator.reactive.exception
org.xmloperator.reactive.element.exception
org.xmloperator.reactive.element
org.xmloperator.reactive.element.impl
org.xmloperator.reactive.element.constraint
org.xmloperator.reactive.element.agent
org.xmloperator.reactive.exception
org.xmloperator.reactive
org.xmloperator.reactive.agent
org.xmloperator.reactive.element
org.xmloperator.reactive.element.impl
org.xmloperator.reactive.element.util

Demonstration

This section focuses on the programs that have been developed for the demonstration of the ReactiveMachine.

Conduct a test

It's actually a single Java program Test.main() that performs a series of tests. Each test is realized by a procedure, which executes the following instructions:

  1. A ReactiveMachine is instancied using the ReactiveFactoryImpl.REACTIVE_FACTORY.

  2. A first Agent is launched. It may launch others.

  3. A ReactiveMachine.done() call can be made when the first Agent has completed his launch. This done order will remain pending as long as an Agent alive.

  4. Each Agent, at one point, decides to terminate.

  5. The ReactiveMachine detects that there is no one living Agent and terminates. The test procedure is terminated. A new one can begin.

A CrashingReport object stores data about Agent crashing. At the end, if no crash is detected, the following message is printed on System.out:

No agent crashes

The various tests are described in the following sections.

ConceptContractImplementation
Test
org.xmloperator.reactive.demo.
Test
CrashingReport
org.xmloperator.reactive.
CrashingReport
org.xmloperator.reactive.demo.
CrashingReportImpl

Stop/Suspend

This is a very basic test.

One Agent is launched. It executes one stop and two suspend. The effect is the same: going to the next instant.

Syracuse

This a stress test for launching agents.

The SyracuseAgent recursively launches new instances of itself. Once a target is reached an ExitAction is generated, destined to the ExitBoard.

ConceptImplementation
SyracuseAgent
org.xmloperator.reactive.demo.syracuse.
SyracuseAgent

Event Order

This test concerns elementary events.

An EventListenerAgent creates and launches a number of EventGeneratorAgent, each one associated with an elementary Event. Each generator Agent generates its own Event at each instant. The listener Agent notes at each instant the order of received events. Arrived at a given instant, the different sequences and their frequencies are displayed. The result differs from one Java virtual machine to another.

ConceptImplementation
EventListenerAgent
org.xmloperator.reactive.demo.event.
EventListenerAgent
EventGeneratorAgent
org.xmloperator.reactive.demo.event.
EventGeneratorAgent

Battle

This is another test about elementary events.

Four players meet for a card game. At the beginning, each player has eight cards in hand. They are marked 0-7 (the zero card is the highest) and are shuffled. Each turn each player reveals his first card. The highest card wins all the other. In case of equality (battle) the involved players reveal a new card. A player loses when he has no cards. The last wins.

Each card of each player is represented by an elementary Event. The role of a player is held by a BattlePlayerAgent.

ConceptImplementation
BattlePlayerAgent
org.xmloperator.reactive.demo.battle.
BattlePlayerAgent

Pass ball

This test is about Message events.

Three players are in a circle. A player who receives a ball from the left returns it to the right and vice versa. The game begins when a player throws a ball to his right and one on his left.

A player is represented by a BallPlayerAgent. Passing a ball to another player is generating a Message that contains the entity identifier of the destination Agent.

ConceptImplementation
BallPlayerAgent
org.xmloperator.reactive.demo.ball.
BallPlayerAgent

Market

This test is similar to a real simulation. It evokes a trading room where shared values are called resources.

There are two main types of actor:

A transaction uses three instants:

ConceptImplementation
Operator
org.xmloperator.reactive.demo.market.agent.
Operator
Transformer
org.xmloperator.reactive.demo.market.agent.
Transformer

Land

This test concerns located agents. The space consists of a Graph of Stations.

Each Agent is located in one Station (through an AgentLocation) at a given instant. Each Station delivers some resource, called AgentEnergy, that supply the agents it hosts. The amount of energy delivered by a Station in one instant is the same at each instant and is shared by the hosted agents. Each Agent obtains an equal part.

An Agent can store a certain amount of energy. A part of this energy is consumed at each instant. An agent whose supply is not sufficient has to move to another Station, in the hope of being better fed, because an agent with no energy dies.

Moves are oriented by strategies, called NavigationStrategy. Each Agent belongs to an AgentFamily to which is attached a NavigationStrategy. Competition will determine the best NavigationStrategy in order to survive.

A well-supplied agent can proceed to cell division. This has the effect of enlarging the corresponding AgentFamily. At the opposite, two poor agents can fusion, in the hope of surviving longer.

Each Agent, called BodyAgent, has an AgentBody, which is its public face. AgentFamily belongs to AgentBody, not AgentEnergy.

ConceptContractImplementation
Stations
org.xmloperator.reactive.demo.land.
Stations
org.xmloperator.reactive.demo.land.impl.
StationsImpl
Station
org.xmloperator.reactive.demo.land.
Station
org.xmloperator.reactive.demo.land.impl.
StationImpl
NavigationStrategy
org.xmloperator.reactive.demo.land.
NavigationStrategy
org.xmloperator.reactive.demo.land.navigation.
[..]NavigationStrategy
AgentFamily
org.xmloperator.reactive.demo.land.
AgentFamily
org.xmloperator.reactive.demo.land.impl.
AgentFamilyImpl
AgentBody
org.xmloperator.reactive.demo.land.
AgentBody
org.xmloperator.reactive.demo.land.agent.
BodyAgent.AgentBodyImpl
AgentLocation
org.xmloperator.reactive.demo.land.
AgentLocation
org.xmloperator.reactive.demo.land.agent.
BodyAgent.AgentLocationImpl
AgentEnergy
org.xmloperator.reactive.demo.land.
AgentEnergy
org.xmloperator.reactive.demo.land.agent.
BodyAgent.AgentEnergyImpl
BodyAgent
org.xmloperator.reactive.demo.land.agent.
BodyAgent

Packages

-----------------
Dependent_package
Used_package
-----------------
org.xmloperator.reactive.demo.ball
org.xmloperator.reactive
org.xmloperator.reactive.impl
org.xmloperator.reactive.agent
org.xmloperator.reactive.demo.battle
org.xmloperator.reactive
org.xmloperator.reactive.agent
org.xmloperator.reactive.demo.event
org.xmloperator.reactive
org.xmloperator.reactive.agent
org.xmloperator.reactive.demo.syracuse
org.xmloperator.reactive.exception
org.xmloperator.reactive
org.xmloperator.reactive.impl
org.xmloperator.reactive.agent
org.xmloperator.reactive.demo.market.util
org.xmloperator.reactive.demo.market
org.xmloperator.reactive.exception
org.xmloperator.reactive
org.xmloperator.reactive.demo.market.impl
org.xmloperator.reactive.exception
org.xmloperator.reactive
org.xmloperator.reactive.impl
org.xmloperator.reactive.demo.market
org.xmloperator.reactive.demo.market.util
org.xmloperator.reactive.demo.market.action
org.xmloperator.reactive.impl
org.xmloperator.reactive.demo.market
org.xmloperator.reactive.demo.market.agent
org.xmloperator.reactive.exception
org.xmloperator.reactive
org.xmloperator.reactive.agent
org.xmloperator.reactive.demo.market
org.xmloperator.reactive.demo.market.impl
org.xmloperator.reactive.demo.market.action
org.xmloperator.reactive.demo.market.data
org.xmloperator.reactive.demo.market
org.xmloperator.reactive.demo.market.impl
org.xmloperator.reactive.demo.market.action
org.xmloperator.reactive.demo.market.agent
org.xmloperator.reactive.demo.land
org.xmloperator.reactive.exception
org.xmloperator.reactive
org.xmloperator.reactive.demo.land.navigation
org.xmloperator.reactive.demo.land
org.xmloperator.reactive.demo.land.impl
org.xmloperator.reactive.exception
org.xmloperator.reactive
org.xmloperator.reactive.impl
org.xmloperator.reactive.demo.land
org.xmloperator.reactive.demo.land.navigation
org.xmloperator.reactive.demo.land.sphere
org.xmloperator.reactive
org.xmloperator.reactive.demo.land.sphere.impl
org.xmloperator.reactive.demo.land.sphere
org.xmloperator.reactive.demo.land.action
org.xmloperator.reactive.impl
org.xmloperator.reactive.demo.land
org.xmloperator.reactive.demo.land.agent
org.xmloperator.reactive.exception
org.xmloperator.reactive
org.xmloperator.reactive.agent
org.xmloperator.reactive.demo.land
org.xmloperator.reactive.demo.land.navigation
org.xmloperator.reactive.demo.land.impl
org.xmloperator.reactive.demo.land.sphere.impl
org.xmloperator.reactive.demo.land.action
org.xmloperator.reactive.demo
org.xmloperator.reactive.exception
org.xmloperator.reactive
org.xmloperator.reactive.agent
org.xmloperator.reactive.demo.ball
org.xmloperator.reactive.demo.battle
org.xmloperator.reactive.demo.event
org.xmloperator.reactive.demo.syracuse
org.xmloperator.reactive.demo.market.impl
org.xmloperator.reactive.demo.market.data
org.xmloperator.reactive.demo.land.navigation
org.xmloperator.reactive.demo.land.agent

Installation

The ReactiveMachine software is provided in source form exclusively. Its execution display needs a Java development platform, such as Eclipse.

In order to install the software with Eclipse you have to:

  1. create a new Java project (File / New / Java Project),
  2. give it a name,
  3. copy the provided source directory content into the project source directory,
  4. refresh the project hierarchy (File / Refresh).

The ReactiveMachine software uses a JavaSE-1.6 JRE System Library.

Running the software (Run / Run) needs to specify its main class: org.xmloperator.reactive.demo.Test


Last update: 2012-01-04 Copyright (c) 2008, 2012 The_xmloperator_project