com.zynaptic.reaction
Interface Reactor

All Known Implementing Classes:

ReactorCore

public interface Reactor

Defines the user API for accessing the reactor object. The reactor object provides access to the various Reaction services via this interface. The reactor object is a singleton, so a reference to this interface can only be obtained via the getReactor static method on the ReactorCore class.

Method Summary

void	cancelThread(Threadable<?,?> threadable) Cancels a currently executing threadable task.
void	cancelTimer(Timeable<?> timeable) Cancels the timer associated with a given timeable object.
Signal<java.lang.Integer>	getReactorShutdownSignal() Gets a handle on the reactor shutdown signal.
long	getUptime() Gets the elapsed time since the reactor was started.
<T> Deferred<T>	newDeferred() Creates a new deferred event object.
<T> DeferredConcentrator<T>	newDeferredConcentrator() Creates a new deferred callback concentrator object.
<T> DeferredSplitter<T>	newDeferredSplitter() Creates a new deferred callback splitter object.
<T> Signal<T>	newSignal() Creates a new signal event object.
<T,U> Deferred<U>	runThread(Threadable<T,U> threadable, T data) Starts executing a threadable task in a new thread.
<T> void	runTimerOneShot(Timeable<T> timeable, int msDelay, T data) Starts a one-shot timer.
<T> void	runTimerRepeating(Timeable<T> timeable, int msDelay, int msInterval, T data) Starts a repeating timer.

Method Detail

getUptime

long getUptime()

Gets the elapsed time since the reactor was started. This method is used to obtain the current value of the reactor's monotonic clock. This allows other components in the system to use the monotonic clock source when required.

Returns:

Returns the number of milliseconds which have elapsed since the reactor started up.

runTimerOneShot

<T> void runTimerOneShot(Timeable<T> timeable,
                         int msDelay,
                         T data)
                     throws ReactorNotRunningException

Starts a one-shot timer. This method is used to submit a one-shot timed callback request to the reactor. If the specified timeable object is already associated with a running timer, the timer will be restarted with the new parameters.

Type Parameters:

T - This type identifier specifies the type of the timer data object which will be passed as the parameter of the timed callback.

Parameters:

timeable - This is the timeable object which will have its timed callback executed after the requested delay.

msDelay - This parameter specifies the delay before the timed callback is to be issued, expressed in milliseconds.

data - This is a timer data object which will be passed back as a parameter to the timed callback.

Throws:

ReactorNotRunningException - This runtime exception will be thrown if an attempt is made to schedule a timer when the reactor is not running.

runTimerRepeating

<T> void runTimerRepeating(Timeable<T> timeable,
                           int msDelay,
                           int msInterval,
                           T data)
                       throws ReactorNotRunningException

Starts a repeating timer. This method is used to submit a repeating timed callback request to the reactor. If the specified timeable object is already associated with a running timer, the timer will be restarted with the new parameters.

Type Parameters:

T - This type identifier specifies the type of the timer data object which will be passed as the parameter of the timed callback.

Parameters:

timeable - This is the timeable object which will have its timed callback executed at the requested interval.

msDelay - This is the delay before the first timed callback is issued, specified in milliseconds.

msInterval - This is the interval at which timed callbacks will be issued, specified in milliseconds. If set to 0 or a negative value, the timer is treated as a one-shot timer.

data - This is a timer data object which will be passed back as a parameter to the timed callbacks.

Throws:

ReactorNotRunningException - This exception will be thrown if an attempt is made to schedule a timer when the reactor is not running.

cancelTimer

void cancelTimer(Timeable<?> timeable)

Cancels the timer associated with a given timeable object. There is a one-to-one mapping between timers and their associated timeable objects. By specifying a timeable object as the parameter to this method, the corresponding timer will be cancelled if it is currently running.

Parameters:

timeable - This is the timeable object for which the associated running timer should be cancelled.

runThread

<T,U> Deferred<U> runThread(Threadable<T,U> threadable,
                            T data)
                      throws ReactorNotRunningException,
                             ThreadableRunningException

Starts executing a threadable task in a new thread. This method submits a threadable task to the reactor to be run in the context of an independent thread. Threads are managed by the reactor using a thread pool, so individual threads will be recycled to execute successive threadable tasks. This means that threadable task objects must not make any assumptions about the thread context in which they are running.

Type Parameters:

T - This type identifier specifies the data type of the parameter which will be passed as an input to the threadable task.

U - This type identifier specifies the data type of the value which will be returned by the threadable task.

Parameters:

threadable - This is the threadable task object which is to be executed in a separate thread.

data - This is the input data object which will be passed to the run method of the threadable task object when it is called in the context of the new thread.

Returns:

Returns a deferred event object which will have its callbacks executed when the threadable task completes successfully or its errbacks executed if the threadable task throws an exception.

Throws:

ReactorNotRunningException - This exception will be thrown if an attempt is made to schedule execution of a threadable task object when the reactor is not running.

ThreadableRunningException - This runtime exception is thrown when an attempt is made to schedule a threadable object for execution while it is already being processed by the reactor. This constitutes a programming error.

cancelThread

void cancelThread(Threadable<?,?> threadable)

Cancels a currently executing threadable task. This method is used to request that a currently running threadable task object has its execution cancelled. From the perspective of the threadable task object, cancellation uses the standard thread interruption mechanism.

Parameters:

threadable - This is the threadable task object for which threaded execution is to be cancelled.

newDeferred

<T> Deferred<T> newDeferred()

Creates a new deferred event object. This method is used as a factory for deferred event objects which implement the Deferred interface.

Type Parameters:

T - This type identifier specifies the data type of the object which should be passed as the callback parameter for the new deferred event object.

Returns:

Returns a deferred event object for which the application code is responsible for issuing callbacks or errbacks.

newDeferredSplitter

<T> DeferredSplitter<T> newDeferredSplitter()

Creates a new deferred callback splitter object. This method is used as a factory for deferred callback splitter objects which implement the DeferredSplitter interface.

Type Parameters:

T - This type identifier specifies the type of the callback data object which will be passed through the deferred splitter.

Returns:

Returns a newly created deferred callback splitter object.

newDeferredConcentrator

<T> DeferredConcentrator<T> newDeferredConcentrator()

Creates a new deferred callback concentrator object. This method is used as a factory for deferred callback concentrator objects which implement the DeferredConcentrator interface.

Type Parameters:

T - This type identifier specifies the type of the callback data object which will be passed through the deferred concentrator.

Returns:

Returns a newly created deferred callback concentrator object.

newSignal

<T> Signal<T> newSignal()

Creates a new signal event object. This method is used as a factory for signal event objects which implement the Signal interface.

Type Parameters:

T - This type identifier specifies the type of the data object which will be passed as the parameter to the onSignal signalable callbacks.

Returns:

Returns a new signal event object which can be used by the application to generate signal events.

getReactorShutdownSignal

Signal<java.lang.Integer> getReactorShutdownSignal()

Gets a handle on the reactor shutdown signal. This method is used to obtain a handle on the reactor shutdown signal event object. This allows application components to register with the signal in order to receive notification that the reactor is shutting down.

Returns:

Returns the signal which is used by the reactor in order to notify subscribers of reactor shutdown. The signal will pass an integer value as the data parameter which will be set to zero for normal shutdown.