javax.realtime

Class Clock

java.lang.Object

javax.realtime.Clock

All Implemented Interfaces:

Chronograph

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

Jamaica Real-Time Specification for Java class Clock.

A clock provides means to determine the current time (now) with a given resolution.

Constructor Summary

Constructors

Constructor and Description
Clock() Constructor to be called by subclasses of Clock.

Method Summary

Modifier and Type	Method and Description
RelativeTime	getDrivePrecision() Returns the resolution for driving events from this clock, i.e.
RelativeTime	getDrivePrecision(RelativeTime dest) Returns the resolution for driving events from this clock, i.e.
RelativeTime	getEpochOffset() Determines the time on the UTC clock when this chronograph was zero.
RelativeTime	getQueryPrecision() Obtain the precision with which time can be read, i.e., the nominal interval between ticks.
RelativeTime	getQueryPrecision(RelativeTime dest) Obtain the precision with which time can be read, i.e., the nominal interval between ticks.
static Clock	getRealtimeClock() Returns the default RealtimeClock.
abstract RelativeTime	getResolution() Obtains the resolution of reading this clock, i.e.
AbsoluteTime	getTime() Determines the current time.
abstract AbsoluteTime	getTime(AbsoluteTime time) Obtain the current time.
static Clock	getUniversalClock() Returns the default UniversalClock.
static void	setRealtimeClock(Clock clock) Sets the system default realtime clock.
abstract void	setResolution(RelativeTime resolution) Sets the resolution of this time to the provided value.
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, isUpdated, lastSynchronized, lastSynchronized

Constructor Detail

Clock

public Clock()

Constructor to be called by subclasses of Clock.

Since this class is abstract, this constructor cannot be called from a class that is not a sub-class of Clock, it should therefore better be protected.

Method Detail

getRealtimeClock

public static Clock getRealtimeClock()

Returns the default RealtimeClock. The result is the singleton instance of this clock.

For JamaicaVM, on systems that have a timer that is synchronized with the external world, this returns a RealtimeClock that is synchronized with the external world. On systems whose timer is not synchronized with the external world, the time of the returned RealtimeClock may be different to the time used by the external world (e.g., the epoch may start at system boot time).

Returns:

the default RealtimeClock, will be located in HeapMemory.

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()

Returns the default UniversalClock. The result is the singleton instance of this clock.

For JamaicaVM, on systems that have a timer that is synchronized with the external world, this returns a UniversalClock that is synchronized with the external world. On systems whose timer is not synchronized with the external world, the time of the returned UniversalClock may be different to the time used by the external world (e.g., the epoch may start at system boot time).

Returns:

the default UniversalClock, will be located in HeapMemory.

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 time on the UTC clock when this chronograph was zero.

Specified by:

getEpochOffset in interface Chronograph

Returns:

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

Throws:

UninitializedStateException - when UTC time is not yet available.

StaticUnsupportedOperationException

Since:

RTSJ 1.0.1

getResolution

public abstract RelativeTime getResolution()

Obtains the resolution of reading this clock, i.e. the constant time interval between two consecutive ticks.

Returns:

the resolution of this clock, allocated in a new object

Throws:

StaticUnsupportedOperationException - when getting the time resolution is not supported for the given clock.

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 this its chronograph.

getTime

public abstract AbsoluteTime getTime(AbsoluteTime time)

Obtain 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 chronograph'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:

time - 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 V1.0.1 the return value is AbsoluteTime and no longer void.

setResolution

public abstract void setResolution(RelativeTime resolution)

Sets the resolution of this time to the provided value.

Parameters:

resolution - the new resolution.

Throws:

StaticIllegalArgumentException - if parameter is null or represents a negative or zero interval.

StaticUnsupportedOperationException - when setting the time resolution is not supported for the given clock.

getQueryPrecision

public RelativeTime getQueryPrecision(RelativeTime dest)

Obtain the precision with which time can be read, i.e., the nominal interval between ticks. It is the same as calling getQueryPrecision(RelativeTime) with null as an argument.

Specified by:

getQueryPrecision in interface Chronograph

Parameters:

dest - the time object to fill.

Returns:

a newly allocated time value holding the read precision.

Since:

RTSJ 2.0

getQueryPrecision

public RelativeTime getQueryPrecision()

Obtain the precision with which time can be read, i.e., the nominal interval between ticks. It is the same as calling getQueryPrecision(RelativeTime) with null as an argument.

Specified by:

getQueryPrecision in interface Chronograph

Returns:

a newly allocated time value holding the read precision.

Since:

RTSJ 2.0

getDrivePrecision

public RelativeTime getDrivePrecision()

Returns the resolution for driving events from this clock, i.e. the constant time interval between two consecutive ticks.

getDrivePrecision

public RelativeTime getDrivePrecision(RelativeTime dest)

Returns the resolution for driving events from this clock, i.e. the constant time interval between two consecutive ticks.

Parameters:

dest - A time object to fill.

Returns:

the resolution of this clock, allocated in a new object

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.Clock, 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

Since:

since RTSJ 2.0