at.borkowski.spicej.impl

Class RealTimeTickSource

java.lang.Object

at.borkowski.spicej.impl.AbstractTickSource

at.borkowski.spicej.impl.RealTimeTickSource

All Implemented Interfaces:

TickSource

public class RealTimeTickSource
extends AbstractTickSource

A tick source bound to real time. Any tick interval can be specified in nanoseconds, but obviously the platform poses natural bounds for this interval. The lower bound is the resolution of System.nanoTime(), the upper bound is Integer.MAX_VALUE. Ticks are generated at a fixed tick-to-tick interval, regardless of the duration of handling ticks. If the handling of ticks for all is not finished until the next tick, one or more subsequent ticks will be fired immediately. Ticks start at 0 and are processed in single-threaded mode. If the last tick listener has been removed from this source, it shuts itself down via stop(), if it's not set to keepAlive mode using setKeepAlive(boolean).

Field Summary

Fields

Modifier and Type	Field and Description
static long	BUSY_WAITING_THRESHOLD The threshold below which busy waiting is employed.
static long	MILLISECOND_THRESHOLD The threshold above which a different implementation of the internal timer is used, which is only considering milliseconds.

Fields inherited from class at.borkowski.spicej.impl.AbstractTickSource

listeners

Constructor Summary

Constructors

Constructor and Description
RealTimeTickSource(long nanoSecondsPerTick) Creates a running real time tick source with ticks generated at the given interval.
RealTimeTickSource(long nanoSecondsPerTick, boolean start) Creates a tick source with ticks generated at the given interval.

Method Summary

Modifier and Type	Method and Description
void	removeListener(TickListener listener) If the last tick listener has been removed from this source, it shuts itself down via stop(), if it's not set to keepAlive mode using setKeepAlive(boolean).
void	reset() Resets the tick source to its initial state.
void	setKeepAlive(boolean keepAlive) Sets the keepAlive mode of this tick source.
void	start() Starts generating tick events, starting from 0.
void	stop() Stops generating tick events.

Methods inherited from class at.borkowski.spicej.impl.AbstractTickSource

addListener, doTick, getCurrentTick

Methods inherited from class java.lang.Object

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

Field Detail

BUSY_WAITING_THRESHOLD

public static final long BUSY_WAITING_THRESHOLD

The threshold below which busy waiting is employed. Waiting via Java sleep methods has the advantage of reduced CPU usage, however, a certain time cost is encountered. Therefore, intervals below BUSY_WAITING_THRESHOLD are implemented with busy waiting. Intervals above are implemented by synchronized waiting. On the current development machine, this threshold had to be at least a value of 4.2 ms to ensure the real-time tests passing, which is why 15 ms have been chosen as a margin. Above 10 ms of threshold, an constat error rate of less than 1 % was measured.

See Also:

Constant Field Values

MILLISECOND_THRESHOLD

public static final long MILLISECOND_THRESHOLD

The threshold above which a different implementation of the internal timer is used, which is only considering milliseconds. This means that above this threshold, the precision of this tick source is reduced to milliseconds.

See Also:

Constant Field Values

Constructor Detail

RealTimeTickSource

public RealTimeTickSource(long nanoSecondsPerTick)

Creates a running real time tick source with ticks generated at the given interval.

Parameters:

nanoSecondsPerTick - the interval of ticks in nanoseconds

RealTimeTickSource

public RealTimeTickSource(long nanoSecondsPerTick,
                          boolean start)

Creates a tick source with ticks generated at the given interval.

Parameters:

nanoSecondsPerTick - the interval of ticks in nanoseconds

start - whether the tick source should be started upon creation

Method Detail

setKeepAlive

public void setKeepAlive(boolean keepAlive)

Sets the keepAlive mode of this tick source. If keepAlive is false (default), the source shuts itself down via stop() upon the removal of the last tick listener. If keepAlive is true, the source stays active.

Parameters:

keepAlive - whether the keepAlive mode should be on

reset

public void reset()

Description copied from interface: TickSource

Resets the tick source to its initial state. The exact outcome is not defined and may be either inside the first tick or in an uninitialized tick state.

Specified by:

reset in interface TickSource

Overrides:

reset in class AbstractTickSource

removeListener

public void removeListener(TickListener listener)

If the last tick listener has been removed from this source, it shuts itself down via stop(), if it's not set to keepAlive mode using setKeepAlive(boolean).

Specified by:

removeListener in interface TickSource

Overrides:

removeListener in class AbstractTickSource

Parameters:

listener - the listener to remove

start

public void start()

Starts generating tick events, starting from 0. This method must not be called when the tick source is already running.

stop

public void stop()

Stops generating tick events. It is not guaranteed how many tick events are generated after the completion of this method, but best effort is made to stop the ticks as soon as possible.