Class: TSyncableClock

Declaration: Clock.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TClock

Inherited By:

None.

Purpose:

A derived class of TClock, providing all of the TClock functionality and more. A TSyncableClock can be synchronized to another TSyncableClock (or TTimeSource). It must be connected to a TTimeSource (directly or indirectly through other clocks). This allows clocks to run in a specifically defined relationship to each other.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Note to deriving classes: If TSyncableClock is overridden, the inherited functions still need to be called. Additional functionality can be layered, or some things can be filtered, but it cannot be replaced. This restriction is because TSyncableClock is the interface with the whole time source syncable clock hierarchy framework, and the framework is not derivable. For example, the virtual GetRate and SetRate functions do not access local data, but make a request to a client to get the data from the time source. TSyncableClock::AddAlarm uses that same server data for the rate instead of calling TSyncableClock::GetRate.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Member Function: TSyncableClock::~TSyncableClock

virtual ~ TSyncableClock ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TClockException::kNoClock if it cannot find the clock.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSyncableClock::Now

virtual void Now (TTime & theTime) const

Interface Category:

API.

Purpose:

Gets the current time.

Calling Context:

Call this function directly.

Parameters:

TTime & theTime -TheTime is set to the current time.

Return Value:

None.

Exceptions:

Throws TClockException::kNoClock if it cannot find the clock. Throws TClockException::kNoSurRootClock if the time source gives a bad handle to the surrogate time source.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSyncableClock::DelayUntil

virtual void DelayUntil (const TTime & pointInTime)

Interface Category:

API.

Purpose:

Delays the calling thread until the pointInTime is current or in the past.

Calling Context:

Called directly by the thread that wants to delay.

Parameters:

const TTime & pointInTime -The point in time that the calling thread delays until it is current or in the past.

Return Value:

None.

Exceptions:

Throws TClockException::kNoClock if it cannot find the clock. Throws TClockException::kDelayCanceled if the delay was canceled.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSyncableClock::SyncToKeepMyTime

virtual void SyncToKeepMyTime (const TSyncableClockSurrogate & masterClock, double newRate =1.0)

Interface Category:

API.

Purpose:

Syncs to masterClock at newRate and keeps the same time.

Calling Context:

Call this function directly.

Parameters:

const TSyncableClockSurrogate & masterClock -The clock to sync to.
double newRate =1.0 -The rate that the clock should sync to.

Return Value:

None.

Exceptions:

Throws TClockException::kNoClock if it cannot find the clock. Throws TClockException::kBadClockDependency if this clock is the same as the masterClock, or if the new master clock is dependent on this clock.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSyncableClock::SyncTo

virtual void SyncTo (const TSyncableClockSurrogate & masterClock, double newRate =1.0, const TTime & offsetFromMasterClock =TTime :: kZero)

Interface Category:

API.

Purpose:

Syncs to masterClock with newRate, and the time of masterClock + offsetFromMasterClock.

Calling Context:

Call this function directly.

Parameters:

const TSyncableClockSurrogate & masterClock -The clock to sync to.
double newRate =1.0 -The new rate.
const TTime & offsetFromMasterClock =TTime :: kZero -The offset from the new master clock.

Return Value:

None.

Exceptions:

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSyncableClock::SetRate

virtual void SetRate (double rate)

Interface Category:

API.

Purpose:

Changes the rate at which the clock is synced to its master, but keeps its current time.

Calling Context:

Call this function directly.

Parameters:

double rate -The new rate.

Return Value:

None.

Exceptions:

Throws TClockException::kNoClock if it cannot find the clock.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSyncableClock::GetRate

virtual double GetRate () const

Interface Category:

API.

Purpose:

Gets the clock's rate.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The rate.

Exceptions:

Throws TClockException::kNoClock if it cannot find the clock.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSyncableClock::SetTime

virtual void SetTime (const TTime & newTime)

Interface Category:

API.

Purpose:

Sets the current time of the clock. The offset is changed to make this work.

Calling Context:

Call this function directly.

Parameters:

const TTime & newTime -The new time.

Return Value:

None.

Exceptions:

Throws TClockException::kNoClock if it cannot find the clock.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSyncableClock::SetTimeRelative

virtual void SetTimeRelative (const TTime & deltaTime)

Interface Category:

API.

Purpose:

Sets Time to the current time + deltaTime and changes the offset.

Calling Context:

Call this function directly.

Parameters:

const TTime & deltaTime -The time to add to the current time.

Return Value:

None.

Exceptions:

Throws TClockException::kNoClock if it cannot find the clock.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSyncableClock::GetOffset

virtual void GetOffset (TTime & offsetTime)

Interface Category:

API.

Purpose:

Gets the offset time from the master clock.

Calling Context:

Call this function directly.

Parameters:

TTime & offsetTime -Set to the current offset time.

Return Value:

None.

Exceptions:

Throws TClockException::kNoClock if it cannot find the clock.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSyncableClock::SetOffset

virtual void SetOffset (const TTime & offsetTime)

Interface Category:

API.

Purpose:

Sets the offset time from the master clock.

Calling Context:

Called directly

Parameters:

const TTime & offsetTime -The new offset time.

Return Value:

None.

Exceptions:

Throws TClockException::kNoClock if it cannot find the clock.

Concurrency:

Multithread safe.

Other Considerations:

Changes the current time.

Member Function: TSyncableClock::Stop

virtual void Stop ()

Interface Category:

API.

Purpose:

Stops the clock.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TClockException::kNoClock if it cannot find the clock.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSyncableClock::Start

virtual void Start ()

Interface Category:

API.

Purpose:

Starts the clock running again if it was stopped.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TClockException::kNoClock if it cannot find the clock.

Concurrency:

Multithread safe.

Other Considerations:

The clock continues running from the same time.

Member Function: TSyncableClock::operator=

TSyncableClock & operator =(const TSyncableClock & aClock)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TSyncableClock & aClock -The source object for the assignment.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Concurrency:

Multithread safe.

Other Considerations:

Actually syncs this clock to master clock of the clock to be assigned, with the same rate, offset, and time as the clock to be assigned.

Member Function: TSyncableClock::GetClockSurrogate

virtual void GetClockSurrogate (TSyncableClockSurrogate & sur) const

Interface Category:

API.

Purpose:

Gets a clock surrogate for the syncable clock.

Calling Context:

Gets a clock surrogate to sync to with a TSyncableClock.

Parameters:

TSyncableClockSurrogate & sur -Surrogate for the TSyncableClock.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSyncableClock::TSyncableClock

TSyncableClock ()
TSyncableClock (const TSyncableClock & aClock)
TSyncableClock (const TSyncableClockSurrogate & aClock, double newRate =1.0, const TTime & offsetFromMasterClock =TTime :: kZero)
TSyncableClock (const TLocalObjectInstance & theRootClockRame)

Interface Category:

API.

Purpose:

Default constructor. Automatically connects to the system time source.
Copy constructor.
Creates a clock synced to aClock at the newRate with an offset of offsetFromMasterClock.
Creates a clock synced to a TTimeSource with theRootClockName.

Calling Context:

Called by the stream-in operators and most real time users.
Called to copy an object.
A short hand for creating a clock then syncing to a surrogate.
Creates clocks directly connected to a TTimeSource.

Parameters:

Takes no parameters.
const TSyncableClock & aClock -The clock to be copied.
const TSyncableClockSurrogate & aClock -The surrogate for the clock to sync to.
double newRate =1.0 -The rate to sync to the clock.
const TTime & offsetFromMasterClock =TTime :: kZero -The offset from the clock.
const TLocalObjectInstance & theRootClockName -The name of the server for the TTimeSource.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through. Throws TClockException::kNoClock if it cannot find the clock.

Concurrency:

Multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.