javax.realtime

Class Clock

java.lang.Object

javax.realtime.Clock

All Implemented Interfaces:

Chronograph

public abstract class Clock
extends java.lang.Object
implements Chronograph

A clock marks the passing of time. It has a concept of now that can be queried through Clock.getTime(), and it can have events queued on it which will be fired when their appointed time is reached.

Note that while all Clock implementations use representations of time derived from HighResolutionTime, which expresses its time in milliseconds and nanoseconds, a particular Clock may track time that is not delimited in seconds or not related to wall clock time in any particular fashion (e.g., revolutions or event detections). In this case, the Clock's timebase should be mapped to milliseconds and nanoseconds in a manner that is computationally appropriate.

Constructor Summary

Constructors

Constructor and Description
Clock() Constructor for the abstract class.

Method Summary

Modifier and Type	Method and Description
RelativeTime	getDrivePrecision() Gets the precision of the clock for driving events, the nominal interval between ticks that can trigger an event.
RelativeTime	getDrivePrecision(RelativeTime dest) Gets the precision of the clock for driving events, the nominal interval between ticks that can trigger an event.
RelativeTime	getEpochOffset() Determines the difference between the epoch of this clock from the Epoch.
RelativeTime	getQueryPrecision(RelativeTime dest) Obtains the precision with which time can be read, i.e., the nominal interval between ticks.
static Clock	getRealtimeClock() There is always at least one clock object available: the system realtime clock.
abstract RelativeTime	getResolution() Deprecated. since RTSJ 2.0
AbsoluteTime	getTime() Determines the current time.
abstract AbsoluteTime	getTime(AbsoluteTime dest) Obtains the current time.
static Clock	getUniversalClock() A means of obtaining the Universal Time, which has no summer or winter time.
static void	setRealtimeClock(Clock clock) Sets the system default realtime clock.
abstract void	setResolution(RelativeTime resolution) Deprecated. since RTSJ 2.0
static void	setUniversalClock(Clock clock) Sets the system default universal clock.
boolean	wait(java.lang.Object rendezvous, HighResolutionTime<?> deadline) Generic wait function that waits for a waiting for a deadlime.

Methods inherited from class java.lang.Object

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

Methods inherited from interface javax.realtime.Chronograph

getEpochOffset, getQueryPrecision, isUpdated, lastSynchronized, lastSynchronized

Constructor Detail

Clock

public Clock()

Constructor for the abstract class.

Method Detail

getRealtimeClock

public static Clock getRealtimeClock()

There is always at least one clock object available: the system realtime clock. This clock is monotonically increasing and does not need to start at the Epoch. On a POSIX system, it is equivalent to CLOCK_MONOTONIC. It is the default Clock.

Returns:

the singleton instance of the default Clock

setRealtimeClock

public static void setRealtimeClock(Clock clock)

Sets the system default realtime clock.

Parameters:

clock - To be used for the realtime clock. When null, the default realtime clock is set to the original system default.

getUniversalClock

public static Clock getUniversalClock()
                               throws StaticUnsupportedOperationException,
                                      UninitializedStateException

A means of obtaining the Universal Time, which has no summer or winter time. Local time can be obtained by adding the appropriate time zone offset. Such a time source is not available on all systems and may take a while to set up on some systems which support it. It is not guarenteed to be monotonic.

Returns:

a Clock that tracts UTC, such as the POSIX CLOCK_REALTIME, when the timezone is set to UTC.

Throws:

StaticUnsupportedOperationException - when the system does not support UTC.

UninitializedStateException - when UTC time is not yet available.

Since:

RTSJ 2.0

setUniversalClock

public static void setUniversalClock(Clock clock)

Sets the system default universal clock.

Parameters:

clock - To be used for the universal clock. When null, the default universal clock is set to the original system default.

Since:

RTSJ 2.0

getEpochOffset

public RelativeTime getEpochOffset()
                            throws StaticUnsupportedOperationException,
                                   UninitializedStateException

Determines the difference between the epoch of this clock from the Epoch. For the UTC, the result is always a RelativeTime value equal to zero. For other clocks, it is a value representing the difference between zero on that clock and zero on the UTC measured on the UTC, where a positive epoc is later than the EPOC.

Specified by:

getEpochOffset in interface Chronograph

Returns:

a newly allocated RelativeTime object in the current execution context with the UTC as its chronograph and containing the time when this chronograph was zero.

Throws:

StaticUnsupportedOperationException - when the chronograph does not have the concept of date.

UninitializedStateException - when UTC time is not yet available.

Since:

RTSJ 1.0.1

getDrivePrecision

public RelativeTime getDrivePrecision()

Gets the precision of the clock for driving events, the nominal interval between ticks that can trigger an event. It is the same as calling getDrivePrecision(RelativeTime) with null as its argument.

Returns:

a value representing the drive precision.

Since:

RTSJ 2.0

getQueryPrecision

public RelativeTime getQueryPrecision(RelativeTime dest)

Obtains the precision with which time can be read, i.e., the nominal interval between ticks. This base implementation does nothing for compatibility and must be overridden in subclasses.

Specified by:

getQueryPrecision in interface Chronograph

Parameters:

dest - To return the relative time value in dest. When dest is null, it allocates a new RelativeTime instance to hold the returned value.

Returns:

the read precision in dest, when dest is not null, or in a newly created object otherwise.

Since:

RTSJ 2.0

getDrivePrecision

public RelativeTime getDrivePrecision(RelativeTime dest)

Gets the precision of the clock for driving events, the nominal interval between ticks that can trigger an event. The result may be larger than that of Chronograph.getQueryPrecision(RelativeTime). The base implementation does nothing for compatibility and must be overridden in subclasses.

Parameters:

dest - To return the relative time value in dest. When dest is null, it allocates a new RelativeTime instance to hold the returned value.

Returns:

dest set to values representing the drive precision.

Since:

RTSJ 2.0

getTime

public AbsoluteTime getTime()

Description copied from interface: Chronograph

Determines the current time. This method returns an absolute time value representing the chronograph's notion of absolute time. For chronographs that do not measure calendar time, this absolute time may not represent a wall clock time.

Specified by:

getTime in interface Chronograph

Returns:

a newly allocated instance of AbsoluteTime in the current allocation context, representing the current time. The returned object has the chronograph from this.

getTime

public abstract AbsoluteTime getTime(AbsoluteTime dest)

Obtains the current time. The time represented by the given AbsoluteTime is changed at some time between the invocation of the method and the return of the method. This method will return an absolute time value that represents this chronographs's notion of the absolute time. For chronographs that do not measure calendar time, this absolute time may not represent a wall clock time.

Specified by:

getTime in interface Chronograph

Parameters:

dest - The instance of AbsoluteTime object which will be updated in place.

Returns:

the instance of AbsoluteTime passed as parameter, or a new object when dest is null. The returned object represents the current time and is associated with this chronograph.

Since:

RTSJ 1.0.1 The return value is updated from void to AbsoluteTime., RTSJ 2.0 When dest is null, a new object is allocated, when not chronograph is overwritten with this.

wait

public boolean wait(java.lang.Object rendezvous,
                    HighResolutionTime<?> deadline)
             throws java.lang.InterruptedException

Generic wait function that waits for a waiting for a deadlime. The time given is a time on the given clock. A user defined clock uses the the rendezvous object to hold the schedulable until the time has elapsed. The caller must be synchronized on rendezvous. This is used to implement both RealtimeThread.sleep(javax.realtime.HighResolutionTime<?>) and RealtimeThread.waitForNextRelease()

Parameters:

rendezvous - an object to wait on until time has passed thus letting the current thread to continue.

deadline - The time when the wait should end

Returns:

true when deadline is reached and false when interrupted before deadline

Throws:

java.lang.InterruptedException - when interrupted

java.lang.IllegalArgumentException - if time is a relative time less than zero or if time is neither AbsoluteTime nor RelativeTime.

Since:

since RTSJ 2.0

setResolution

@Deprecated
public abstract void setResolution(RelativeTime resolution)

Deprecated. since RTSJ 2.0

Sets the resolution of this. For some hardware clocks setting resolution is impossible and when this method is called on those clocks, then an StaticUnsupportedOperationException is thrown.

Parameters:

resolution - The new resolution of this, when the requested value is supported by this clock. When resolution is smaller than the minimum resolution supported by this clock then it throws StaticIllegalArgumentException. When the requested resolution is not available and it is larger than the minimum resolution, then the clock will be set to the closest resolution that the clock supports, via truncation. The value of the resolution parameter is not altered. The clock association of the resolution parameter is ignored.

Throws:

StaticIllegalArgumentException - when resolution is null, or when the requested resolution is smaller than the minimum resolution supported by this clock.

StaticUnsupportedOperationException - when the clock does not support setting its resolution.

getResolution

@Deprecated
public abstract RelativeTime getResolution()

Deprecated. since RTSJ 2.0

Gets the resolution of the clock, the nominal interval between ticks.

Returns:

A newly allocated RelativeTime object representing the resolution of this. The returned object is associated with this clock.

See Also:

getDrivePrecision(), getQueryPrecision(javax.realtime.RelativeTime)