javax.realtime

Class Clock

java.lang.Object

javax.realtime.Clock

All Implemented Interfaces:

Chronograph

public abstract class Clock
extends 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) Gets the precision of the clock for driving events, the nominal interval between ticks that can trigger an event.
RelativeTime	getEpochOffset() Determines the time on the UTC clock when this chronograph was zero.
RelativeTime	getQueryPrecision(RelativeTime dest) Obtains 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() Deprecated. since RTSJ 2.0
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) Deprecated. since RTSJ 2.0
static void	setUniversalClock(Clock clock) Sets the system default universal clock.
boolean	wait(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 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

Throws:

UninitializedStateException - when UTC time is not yet available.

StaticUnsupportedOperationException

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.

Since:

RTSJ 1.0.1

getResolution

@Deprecated
public abstract RelativeTime getResolution()

Deprecated. since RTSJ 2.0

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

Throws:

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

Returns:

the resolution of this clock, allocated in a new object

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

@Deprecated
public abstract void setResolution(RelativeTime resolution)

Deprecated. since RTSJ 2.0

Sets the resolution of this time to the provided value.

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.

Parameters:

resolution - the new resolution.

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)

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). This 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

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

wait

public boolean wait(Object rendezvous,
                    HighResolutionTime<?> deadline)
             throws 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()

Throws:

InterruptedException

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

Since:

since RTSJ 2.0