Class: TDelay

Declaration: LowLevelClock.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

An object interface for a safe, cancelable delay without race conditions. The thread that delays blocks until the delay time, or it returns throwing an exception (kDelayCanceled) if it is canceled. TDelay needs a clock. TDelay can not be copied, streamed, or assigned.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None.

Concurrency:

TDelay is multithread safe as long as only one thread calls the DelayUntil or DelayFor functions. It also avoids race conditions by having a pending cancel.

Resource Use:

No special requirements if the default/empty constructor is used. If the TClock* constructor is used, the creator is responsible for ensuring that the clock is valid as long as the TDelay object is, and that any thread calling either delay function or CancelDelay has the TClock in its address space.

Member Function: TDelay::TDelay

TDelay ()
TDelay (TClock * theClock)

Interface Category:

API.

Purpose:

Default constructor. Uses a TSystemClock.
Uses theClock pointed to. The TClock* must be accessible for the life of the TDelay object, and any thread calling either delay function or CancelDelay must have the TClock in its address space.

Calling Context:

This constructor should be called unless a clock other than the TSystemClock is needed.
This constructor should be called if a clock other than the TSystemClock is needed.

Parameters:

Takes no parameters -TSystemClock is the clock used.
TClock * theClock -theClock is the clock used.

Return Value:

None.

Exceptions:

The delay functions on TSystemClock unblock on any message received from the Interrupt Manager task. These delays will be fixed as soon as CommonPoint has ports. Until then, it throws TClockException::kUnsafeDelay if it receives a message other than its own.

Concurrency:

TDelay is multithread safe as long.

Other Considerations:

Performance will vary depending on the type of clock used. TSystemClock should have the best performance. The delay functions on TSystemClock unblock on any message received from the Interrupt Manager task. These delays will be fixed as soon as CommonPoint has ports. Do not use with a TSystemClock in the UI thread.

Member Function: TDelay::~TDelay

virtual ~ TDelay ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

TDelay is multithread safe as long.

Other Considerations:

If there is a thread currently delayed, it will cancel it before destruction.

Member Function: TDelay::DelayFor

bool DelayFor (const TTime & amountOfTime)

Interface Category:

API.

Purpose:

Delays the calling thread for the amountOfTime. It actually delays the calling thread until the amountOfTime + the current time is current or in the past.

Calling Context:

Only one thread should call either DelayFor or DelayUntil. It can make repeated calls and can call both, but no other thread should call the delay functions.

Parameters:

const TTime & amountOfTime -The amount of time to delay for.

Return Value:

Returns true if delayed until the time current time plus the amountOfTime with out being canceled. Returns false if the delay was canceled (by another thread calling CancelDelay).

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

TDelay is multithread safe as long.

Other Considerations:

Performance will vary depending on the type of clock used. TSystemClock should have the best performance.

Member Function: TDelay::DelayUntil

bool DelayUntil (const TTime & pointInTime)

Interface Category:

API.

Purpose:

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

Calling Context:

Only one thread should call either DelayFor or DelayUntil. It can make repeated calls and can call both, but no other thread should call the delay functions.

Parameters:

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

Return Value:

Returns true if delayed until the pointInTime without being canceled. Returns false if the delay was canceled (by another thread calling CancelDelay).

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

TDelay is multithread safe as long.

Other Considerations:

Performance will vary depending on the type of clock used. TSystemClock should have the best performance.

Member Function: TDelay::CancelDelay

bool CancelDelay ()

Interface Category:

API.

Purpose:

Cancels a delay. This is a pending cancel to avoid any race conditions. If there is a thread currently delaying, it is canceled, and true is returned. Otherwise, it returns false and causes the next thread that tries to delay to be canceled. This guarantees that one delay is canceled, without a race condition. When a delay is canceled,, the delay function returns and a TClockException::kDelayCanceled exception is thrown.

Calling Context:

Called directly to cancel a delay.

Parameters:

Takes no parameters.

Return Value:

Returns true if a delay was active and canceled. Returns false if the cancel will pend and cancel the next attempt to delay.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

TDelay is multithread safe as long.

Other Considerations:

Performance will vary depending on the type of clock used. TSystemClock should have the best performance.

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