com.rubecula.darwin.evolution
Interface Evolution

All Superinterfaces:

Clocked, Evolver, java.lang.Runnable

All Known Implementing Classes:

Evolution_, Evolution_Calendar, Evolution_Standard, Evolution_Timed

public interface Evolution
extends Evolver, java.lang.Runnable

This interface defines the concept of an Evolution. This concept is central to the Darwin framework and forms part of a triad of fundamental concepts:

• Evolution;
• Evolvable, typically a Taxon;
• user interface, typically, but not necessarily, an Applet.

The properties of an Evolution are as follows:

• a map of Evolvable evolvables and their generation frequencies (in ticks of the clock);
• a list (unordered) of GenerationListeners -- after each tick, any evolver which has undergone a new generation will be passed to this listener;
• two modes of running:
  • continuous running (with actions start, pause, resume, stop)
  • stepping (with action next)
• active (a read-only property) -- see isActive(boolean);
• the ability to schedule an (arbitrary) Runnable event at a future time;
• the ability to seed the evolvables by invoking their Theological.seedMembers() methods (this is really just a convenience method).

Note that in general, there will be two modes of updating the user interface, during evolution. The generation listeners fire at the completion of each generation. If you also want to visualize updates at more points during the completion of a generation, then you should also set up VisualizableListeners on an Visualizable objects (such as Populations or Environments).

Author:

Robin Hillyard

Method Summary

boolean	isActive(boolean ignoreEvents)
boolean	isPaused()
void	pause() suppress all new generations until resume() is called.
void	resume() cancel the previous call of pause().
java.util.concurrent.Future<?>	scheduleEvent(long millisecs, java.lang.Runnable event) Schedule an arbitrary event for execution after a specific number of milliseconds.
boolean	shutdown() A terminal shut-down of the Evolution process (including both evolution and scheduled events).
boolean	stop()
boolean	stoppable()
boolean	waitUntilComplete(int delay) Wait for this Evolution to become inactive, then return.

Methods inherited from interface com.rubecula.darwin.evolution.Evolver

addEvolvable, addEvolvable, addListener, cleanup, getClockWatcher, getEvolvableKeys, init, next, removeEvolvable, seedEvolvables, setClockWatcher

Methods inherited from interface com.rubecula.darwin.foundation.Clocked

getClock

Methods inherited from interface java.lang.Runnable

run

Method Detail

isActive

boolean isActive(boolean ignoreEvents)
                 throws EvolutionException

Parameters:

ignoreEvents - XXX

Returns:

true if this evolution is currently active (with valid timer, task and evolvables).

Throws:

EvolutionException

isPaused

boolean isPaused()

Returns:

true if EvolutionTask.isPaused() returns true for the evolution task. XXX is this OK? what if evolutionTask is null?

See Also:

EvolutionTask.isPaused()

pause

void pause()
           throws EvolutionException

suppress all new generations until resume() is called.

Throws:

EvolutionException

resume

void resume()
            throws EvolutionException

cancel the previous call of pause().

Throws:

EvolutionException

scheduleEvent

java.util.concurrent.Future<?> scheduleEvent(long millisecs,
                                             java.lang.Runnable event)

Schedule an arbitrary event for execution after a specific number of milliseconds. The event will fire is scheduled independently of any new generations (and will run in a different thread). Typically, this will be used to change a property in the environment at a certain time. TODO consider implementing in such a way that we can specify a certain number of ticks (the ability to pause/resume makes this complex).

Parameters:

millisecs - the number of millisecs before the event is to be run.

event - the event to be run.

Returns:

the Future for this event, returned by the scheduler

shutdown

boolean shutdown()
                 throws EvolutionException

A terminal shut-down of the Evolution process (including both evolution and scheduled events). Subsequent calls to this Evolution object will not succeed. Compare pause() and stop().

Returns:

the result of calling ExecutorService.awaitTermination(long, TimeUnit) which, roughly speaking, will be true if everything shut down in an orderly fashion.

Throws:

EvolutionException

See Also:

stop()

stop

boolean stop()
             throws EvolutionException

Returns:

true if everything is OK after the stop.

Throws:

EvolutionException

stoppable

boolean stoppable()

Returns:

true if we have permission to stop this Evolution.

waitUntilComplete

boolean waitUntilComplete(int delay)
                          throws EvolutionException

Wait for this Evolution to become inactive, then return.

Parameters:

delay - delay between tests (in milliseconds)

Returns:

true if the evolution is really complete.

Throws:

EvolutionException