com.zynaptic.reaction.core
Class ReactorCore

java.lang.Object
  com.zynaptic.reaction.core.ReactorCore

All Implemented Interfaces:

ReactorControl, Reactor

public final class ReactorCore
extends java.lang.Object
implements Reactor, ReactorControl

Implements the main reactor functionality. This class defines the singleton object which provides all the core functionality of the reactor service. It exposes the user API via the Reactor interface and the reactor control API via the ReactorControl interface.

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.
static Reactor	getReactor() Accesses the reactor user interface.
static ReactorControl	getReactorControl() Accesses the reactor control interface.
Signal<java.lang.Integer>	getReactorShutdownSignal() Gets a handle on the reactor shutdown signal.
long	getUptime() Gets the elapsed time since the reactor was started.
void	join() Waits for the reactor thread to exit.
<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.
void	start(MonotonicClockSource clockSource, ReactorLogTarget logTarget) Starts the reactor running.
void	stop() Requests that the reactor stop running.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getReactor

public static final Reactor getReactor()

Accesses the reactor user interface. This method is used in order to get a handle on the user interface of the singleton reactor component.

Returns:

Returns a handle on the reactor user interface.

getReactorControl

public static final ReactorControl getReactorControl()

Accesses the reactor control interface. This method is used in order to get a handle on the control interface of the singleton reactor component.

Returns:

Returns a handle on the reactor control interface.

start

public final void start(MonotonicClockSource clockSource,
                        ReactorLogTarget logTarget)
                 throws ThreadableRunningException

Description copied from interface: ReactorControl

Starts the reactor running. This method is called in order to start the main reactor thread, using the supplied monotonic clock as its timebase. It is called from a separate host thread and will return once the reactor thread has started running.

Specified by:

start in interface ReactorControl

Parameters:

clockSource - This is a monotonic clock which will be used as the timebase for the reactor.

logTarget - This is the logging service to which all reactor log messages are redirected.

Throws:

ThreadableRunningException - This exception is thrown if there is already a reactor thread running. This indicates a programming error.

stop

public final void stop()

Description copied from interface: ReactorControl

Requests that the reactor stop running. This method is called in order to stop the reactor from running. It may be called from any thread context, including the main reactor thread. This method returns immediately and if the calling thread wishes to wait for the reactor to shut down it should follow it with a call to the join method.

Specified by:

stop in interface ReactorControl

join

public final void join()
                throws java.lang.InterruptedException

Description copied from interface: ReactorControl

Waits for the reactor thread to exit. This method may be called from any thread except the main reactor thread in order to wait for the reactor thread to exit. It is typically called immediately after the host thread has called the stop method.

Specified by:

join in interface ReactorControl

Throws:

java.lang.InterruptedException - This exception is thrown if the calling thread is interrupted before the reactor shutdown is complete. An Error is thrown if the corresponding error condition caused the reactor to shut down.

getUptime

public final long getUptime()

Description copied from interface: Reactor

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.

Specified by:

getUptime in interface Reactor

Returns:

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

getReactorShutdownSignal

public final Signal<java.lang.Integer> getReactorShutdownSignal()

Description copied from interface: Reactor

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.

Specified by:

getReactorShutdownSignal in interface Reactor

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.

runThread

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

Description copied from interface: Reactor

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.

Specified by:

runThread in interface Reactor

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

public final void cancelThread(Threadable<?,?> threadable)

Description copied from interface: Reactor

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.

Specified by:

cancelThread in interface Reactor

Parameters:

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

runTimerOneShot

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

Description copied from interface: Reactor

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.

Specified by:

runTimerOneShot in interface Reactor

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

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

Description copied from interface: Reactor

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.

Specified by:

runTimerRepeating in interface Reactor

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

public final void cancelTimer(Timeable<?> timeable)

Description copied from interface: Reactor

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.

Specified by:

cancelTimer in interface Reactor

Parameters:

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

newDeferred

public final <T> Deferred<T> newDeferred()

Description copied from interface: Reactor

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

Specified by:

newDeferred in interface Reactor

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

public final <T> DeferredSplitter<T> newDeferredSplitter()

Description copied from interface: Reactor

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

Specified by:

newDeferredSplitter in interface Reactor

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

public final <T> DeferredConcentrator<T> newDeferredConcentrator()

Description copied from interface: Reactor

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

Specified by:

newDeferredConcentrator in interface Reactor

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

public final <T> Signal<T> newSignal()

Description copied from interface: Reactor

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

Specified by:

newSignal in interface Reactor

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.