it.unibo.alchemist.core.interfaces.Simulation Maven / Gradle / Ivy
Show all versions of alchemist-interfaces Show documentation
/*
* Copyright (C) 2010-2019, Danilo Pianini and contributors listed in the main project's alchemist/build.gradle file.
*
* This file is part of Alchemist, and is distributed under the terms of the
* GNU General Public License, with a linking exception,
* as described in the file LICENSE in the Alchemist distribution's top directory.
*/
package it.unibo.alchemist.core.interfaces;
import java.util.Optional;
import java.util.concurrent.TimeUnit;
import org.jooq.lambda.fi.lang.CheckedRunnable;
import it.unibo.alchemist.boundary.interfaces.OutputMonitor;
import it.unibo.alchemist.model.interfaces.Environment;
import it.unibo.alchemist.model.interfaces.Neighborhood;
import it.unibo.alchemist.model.interfaces.Node;
import it.unibo.alchemist.model.interfaces.Position;
import it.unibo.alchemist.model.interfaces.Time;
/**
* This interface forces simulations to be independent threads, and make them
* controllable from an external console.
*
* @param
* Concentration type
* @param
* Position Type
*/
public interface Simulation> extends Runnable {
/**
* Adds an {@link OutputMonitor} to this simulation.
*
* @param op
* the OutputMonitor to add
*/
void addOutputMonitor(OutputMonitor op);
/**
* Allows to access the current environment.
*
* @return a reference to the current Environment. The environment is not a
* copy but back-ends the real environment used in the simulation.
* Manipulate it carefully
*/
Environment getEnvironment();
/**
* @return an {@link Optional} containing the exception that made the
* simulation fail, or {@link Optional#empty()} in case the
* simulation is ongoing or has terminated successfully.
*/
Optional getError();
/**
* @return the step at which this simulation will eventually stop.
*/
long getFinalStep();
/**
* Allows to at which time this simulation will end.
*
* @return the final time
*/
Time getFinalTime();
/**
* Allows to access the current status.
*
* @return the current Status of the simulation
*/
Status getStatus();
/**
* Allows to access the current simulation step.
*
* @return the current step
*/
long getStep();
/**
* Allows to know which is the current simulation time.
*
* @return the current time
*/
Time getTime();
/**
* Executes a certain number of steps, then pauses it.
*
* @param steps
* the number of steps to execute
*/
void goToStep(long steps);
/**
* Executes the simulation until the target time is reached, then pauses it.
*
* @param t
* the target time
*/
void goToTime(Time t);
/**
* This method must get called in case a a communication link connecting two
* nodes gets created during the simulation. This method provides dependency
* and scheduling times re-computation for all the reactions interested by
* such change.
*
* @param node
* the node
* @param n
* the second node
*/
void neighborAdded(Node node, Node n);
/**
* This method must get called in case a a communication link connecting two
* nodes gets broken during the simulation. This method provides dependency
* and scheduling times re-computation for all the reactions interested by
* such change.
*
* @param node
* the node
* @param n
* the second node
*/
void neighborRemoved(Node node, Node n);
/**
* This method must get called in case a node is added to the environment
* during the simulation and after its neighborhood has been computed (or
* can be consistently computed by the simulated environment). This method
* provides dependency computation and is responsible of correctly
* scheduling the Node's new reactions.
*
* @param node
* the freshly added node
* @throws IllegalMonitorStateException
* if the method gets called from a different thread than the
* simulation thread
*/
void nodeAdded(Node node);
/**
* This method must get called in case a node is moved in the environment
* during the simulation and after its neighborhood has been computed (or
* can be consistently computed by the simulated environment). This method
* provides dependency computation and is responsible of correctly
* scheduling the Node's reactions.
*
* @param node
* the node
*/
void nodeMoved(Node node);
/**
* This method must get called in case a node is removed from the
* environment during the simulation and after its neighborhood has been
* computed (or can be consistently computed by the simulated environment).
* This method provides dependency computation and is responsible of
* correctly removing the Node's reactions from the scheduler.
*
* @param node
* the freshly removed node
* @param oldNeighborhood
* the neighborhood of the node as it was before it was removed
* (used to calculate reverse dependencies)
*/
void nodeRemoved(Node node, Neighborhood oldNeighborhood);
/**
* Sends a pause command to the simulation. There is no guarantee on when
* this command will be actually processed.
*/
void pause();
/**
* Sends a play command to the simulation. There is no guarantee on when
* this command will be actually processed.
*/
void play();
/**
* Removes an {@link OutputMonitor} to this simulation. If the
* {@link OutputMonitor} was not among those already added, this method does
* nothing.
*
* @param op
* the OutputMonitor to add
*/
void removeOutputMonitor(OutputMonitor op);
/**
* Schedules a runnable to be executed by the Simulation thread, useful for
* synchronization purposes (e.g. make sure that the environment is not
* being changed while the requested operation is being executed). An
* exception thrown by the passed runnable will make the simulation
* terminate.
*
* @param r
* the runnable to execute
*/
void schedule(CheckedRunnable r);
/**
* Sends a terminate command to the simulation. There is no guarantee on when
* this command will be actually processed.
*/
void terminate();
/**
* Suspends the caller until the simulation reaches the selected
* {@link Status}.
*
* @param s
* The {@link Status} the simulation must reach before returning
* from this method
* @param timeout
* The maximum lapse of time the caller wants to wait before
* being resumed (0 means "no limit")
* @param timeunit
* The {@link TimeUnit} used to define "timeout"
*
* @return the status of the Simulation at the end of the wait
*/
Status waitFor(Status s, long timeout, TimeUnit timeunit);
}