Tutorial

English

Français

The suspend instruction

In SugarCubes, one can consider that the execution of an instant is made of a succession of microsteps (or what one also calls activation), which converge in a finite time (finite number of iterations) to a fix point which is the end of the instant. A reactive machine activates its body for each microsteps until the end of instant is reached. So A microstep activates once every components of the program. The suspend and close instructions are used to have finer control over the way components are activated during microsteps. This example shows how a component can explicitly release the control during a microstep. This ensure that every other components have a chance to get activated once before it can continue its execution.

import inria.meije.rc.sugarcubes.*;

// This program shows the use of suspend.

class Suspends
{
    // This static method creates a component with a number
    // which paraterize message displayed by the component
    static Program component(int i){
        return SC.loop(SC.seq(
                              SC.print("program "+i+" phase 1\n")
                              ,SC.suspend()
                              ,SC.print("program "+i+" phase 2\n")
                              ,SC.suspend()
                              ,SC.print("program "+i+" phase 3\n")
                              ,SC.stop() // avoid instantaneous loop
                              )
                        );
    }
    public static void main(String[] args){
        Machine machine = SC.machine();
        machine.addProgram(component(0));
        machine.addProgram(SC.merge(component(1),component(2)));

// One makes the machine reacts for 5 consecutive instants.
        for(int i = 1; i <= 5; i++){
            System.out.println("instant "+i+": ");
            machine.react();
        }
    }
}

Like the instruction stop, the instruction suspend is used in a sequence of instrsuctions. It allows one to explicity suspend the execution of a component in the current micro step. The sequence of instruction will resume its execution after the suspend instruction at the next microstep before the end of the instant.

SC.seq(SC.print("1 "),SC.suspend(),SC.print("2 "),SC.suspend(),SC.print("3 "));

The suspend tells that a body is suspended but must be reactivated before the end of the instant. So in this example the sequence must terminate by a stop instruction to avoid instantaneous loop. Without the stop instruction we have an instantaneous body (a body wich terminate its execution at the very same instant it starts its execution) depsite of the use of the suspend instruction leanding to an infinite loop.

How to compile?

javac -classpath SugarCubesv3.1.0.jar Suspends.java

How to execute?

java -classpath SugarCubesv3.1.0.jar:. Suspends

You should get the following result:

instant 1: 
program 0 phase 1
program 1 phase 1
program 2 phase 1
program 0 phase 2
program 1 phase 2
program 2 phase 2
program 0 phase 3
program 1 phase 3
program 2 phase 3
instant 2: 
program 0 phase 1
program 1 phase 1
program 2 phase 1
program 0 phase 2
program 1 phase 2
program 2 phase 2
program 0 phase 3
program 1 phase 3
program 2 phase 3
instant 3: 
program 0 phase 1
program 1 phase 1
program 2 phase 1
program 0 phase 2
program 1 phase 2
program 2 phase 2
program 0 phase 3
program 1 phase 3
program 2 phase 3
instant 4: 
program 0 phase 1
program 1 phase 1
program 2 phase 1
program 0 phase 2
program 1 phase 2
program 2 phase 2
program 0 phase 3
program 1 phase 3
program 2 phase 3
instant 5: 
program 0 phase 1
program 1 phase 1
program 2 phase 1
program 0 phase 2
program 1 phase 2
program 2 phase 2
program 0 phase 3
program 1 phase 3
program 2 phase 3

The execution of the three components are interleaved during the execution of one instant. While the same program without the use of suspend leads to the execution of the first component the second then the third at each instant without any interleaving.

import inria.meije.rc.sugarcubes.*;

// This program shows the use of suspend.

class No_Suspends
{
    // This static method creates a component with a number
    // which paraterize message displayed by the component
    static Program component(int i){
        return SC.loop(SC.seq(
                              SC.print("program "+i+" phase 1\n")
                              ,SC.nothing() // one replaces suspend with nothing
                              ,SC.print("program "+i+" phase 2\n")
                              ,SC.nothing()
                              ,SC.print("program "+i+" phase 3\n")
                              ,SC.stop() // avoid instantaneous loop
                              )
                        );
    }
    public static void main(String[] args){
        Machine machine = SC.machine();
        machine.addProgram(component(0));
        machine.addProgram(SC.merge(component(1),component(2)));

// One makes the machine reacts for 5 consecutive instants.
        for(int i = 1; i <= 5; i++){
            System.out.println("instant "+i+": ");
            machine.react();
        }
    }
}

How to compile?

javac -classpath SugarCubesv3.1.0.jar No_Suspends.java

How to execute?

java -classpath SugarCubesv3.1.0.jar:. No_Suspends

You should get the following result:

instant 1: 
program 0 phase 1
program 0 phase 2
program 0 phase 3
program 1 phase 1
program 1 phase 2
program 1 phase 3
program 2 phase 1
program 2 phase 2
program 2 phase 3
instant 2: 
program 0 phase 1
program 0 phase 2
program 0 phase 3
program 1 phase 1
program 1 phase 2
program 1 phase 3
program 2 phase 1
program 2 phase 2
program 2 phase 3
instant 3: 
program 0 phase 1
program 0 phase 2
program 0 phase 3
program 1 phase 1
program 1 phase 2
program 1 phase 3
program 2 phase 1
program 2 phase 2
program 2 phase 3
instant 4: 
program 0 phase 1
program 0 phase 2
program 0 phase 3
program 1 phase 1
program 1 phase 2
program 1 phase 3
program 2 phase 1
program 2 phase 2
program 2 phase 3
instant 5: 
program 0 phase 1
program 0 phase 2
program 0 phase 3
program 1 phase 1
program 1 phase 2
program 1 phase 3
program 2 phase 1
program 2 phase 2
program 2 phase 3

The close instruction

import inria.meije.rc.sugarcubes.*;

// This program shows the use of suspend.

class Close
{
    // This static method creates a component with a number
    // which paraterize message displayed by the component
    static Program component(int i){
        return SC.loop(SC.seq(
                              SC.print("program "+i+" phase 1\n")
                              ,SC.suspend()
                              ,SC.print("program "+i+" phase 2\n")
                              ,SC.suspend()
                              ,SC.print("program "+i+" phase 3\n")
                              ,SC.stop() // avoid instantaneous loop
                              )
                        );
    }
    public static void main(String[] args){
        Machine machine = SC.machine();
        machine.addProgram(component(0));
        machine.addProgram(SC.close(SC.merge(component(1),component(2))));

// One makes the machine reacts for 5 consecutive instants.
        for(int i = 1; i <= 5; i++){
            System.out.println("instant "+i+": ");
            machine.react();
        }
    }
}

How to compile?

javac -classpath SugarCubesv3.1.0.jar Close.java

How to execute?

java -classpath SugarCubesv3.1.0.jar:. Close

You should get the following result:

instant 1: 
program 0 phase 1
program 1 phase 1
program 2 phase 1
program 1 phase 2
program 2 phase 2
program 1 phase 3
program 2 phase 3
program 0 phase 2
program 0 phase 3
instant 2: 
program 0 phase 1
program 1 phase 1
program 2 phase 1
program 1 phase 2
program 2 phase 2
program 1 phase 3
program 2 phase 3
program 0 phase 2
program 0 phase 3
instant 3: 
program 0 phase 1
program 1 phase 1
program 2 phase 1
program 1 phase 2
program 2 phase 2
program 1 phase 3
program 2 phase 3
program 0 phase 2
program 0 phase 3
instant 4: 
program 0 phase 1
program 1 phase 1
program 2 phase 1
program 1 phase 2
program 2 phase 2
program 1 phase 3
program 2 phase 3
program 0 phase 2
program 0 phase 3
instant 5: 
program 0 phase 1
program 1 phase 1
program 2 phase 1
program 1 phase 2
program 2 phase 2
program 1 phase 3
program 2 phase 3
program 0 phase 2
program 0 phase 3

Inter-instant tasks

SugarCubes provides a mechanism to execute actions described in Java (let says atomic actions in the sense that as atomic actions in SugarCubes reactive programs, the inter instant task should be executed in a finite time otherwise the overall system will stale) between two consecutive instants. This mechanism allows one to build systems whose reactive program compute a state during the execution of an instant (let says, in a simulation one computes the physical state : position, speed, ..., of various objects involved in the simulation) and which displays its results on screen (for example by writing results on a file or rendering a scene in 3D according to the new state of the objects) at the end of the instant (the end of the state computation) and just before the next reaction.
This simple example illustrates the use of such a mechanism.

Execution of an atomic action when the end of instant is decided

SugarCubes v3.1 introduces a new instruction which allows one to execute an instruction at the end of an instant. The instruction is called task and is a new way to express in a program a similar mechanism as the mechanism of inter instant tasks introduced ins SugarCubes v3. A common problem with the inter-instant task mechanism of SugarCubes v3 is that it doesn't rely on instruction to describe the operationnal semantics of inter-instant taks but on the architecture provided by reactive machine to handle such inter-instant tasks. This