Class: TThreadHandle

Declaration: Task.h

Taxonomy Categories:

Member Functions:

TThreadHandle
operator=
operator==
operator!=
~TThreadHandle
operator<<=
operator>>=
IsEqual
Hash
IsSelf
Exists
PrintableRepresentation
Kill
CopyThreadSchedule
SetThreadSchedule
CancelWaitAndPostException
CheckForPendingCancel
ClearPendingCancel
WaitForDeathOf

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

A concrete class that represents a thread of execution.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Derived classes override or supplement the member functions provided by TThreadHandle to create specialized thread classes.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TThreadHandle::TThreadHandle

TThreadHandle (const TThreadProgram & copyThreadCode)
TThreadHandle (TThreadProgram * adoptThreadCode)
TThreadHandle (EExecution yourself)
TThreadHandle (const TThreadHandle & aThread)
TThreadHandle ()

Interface Category:

API.

Purpose:

Constructor. (API.)
Constructor. (API.)
Constructor. (API.)
Copy constructor. (API.)
Default constructor. (API.)

Calling Context:

Called to create a new thread and start it executing a specific TThreadProgram.
Called to create a new thread and start it executing a specific TThreadProgram.
Called to create a TThreadHandle that represents the currently executing thread.
Called to copy an object.
Called by the stream-in operators.

Parameters:

const TThreadProgram & copyThreadCode -A TThreadProgram reference that will be cloned. The cloned object supplies the execution state for the new thread.
TThreadProgram * adoptThreadCode -A pointer to a TThreadProgram instance that will be adopted and which will supply the execution state for the new thread.
EExecution yourself -An enumeration option. kUseSelf is the only possible value.
const TThreadHandle & aThread -An object to copy.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws TGeneralKernelException(TGeneralKernelException::kBadArgument) if an invalid argument is passed to a constructor.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TThreadHandle::operator=

TThreadHandle & operator =(const TThreadHandle & aThread)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TThreadHandle & aThread -The object that supplies the value for the right-hand side of the assignment statement.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TThreadHandle::operator==

bool operator ==(const TThreadHandle & toWhat) const

Interface Category:

API.

Purpose:

Compares TThreadHandles for equality.

Calling Context:

Called to determine when two TThreadHandle represent the same memory object.

Parameters:

const TThreadHandle & toWhat -The object on the right-hand side of the equality comparator.

Return Value:

Returns true if the two TThreadHandles represent the same memory object. Returns false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TThreadHandle::operator!=

bool operator != (const TThreadHandle & toWhat) const

Interface Category:

API.

Purpose:

Compares TThreadHandles for inequality.

Calling Context:

Called to determine when two TThreadHandles do not represent the same memory object.

Parameters:

const TThreadHandle & toWhat -The object on the right-hand side of the inequality comparator.

Return Value:

Returns true if the two TThreadHandles do not represent the same memory object. Returns false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TThreadHandle::~TThreadHandle

virtual ~ TThreadHandle ()

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:

Not multithread safe.

Other Considerations:

This member function only destroys the TThreadHandle instance and not the kernel entity it represents.

Member Function: TThreadHandle::operator<<=

virtual TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromWhere -The stream the object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws TInvalidVersionError if the object read in from the stream has an invalid version number.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TThreadHandle::operator>>=

virtual TStream & operator >>=(TStream & toWhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & toWhere -The stream the object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TThreadHandle::IsEqual

virtual EComparisonResult IsEqual (const TThreadHandle & right) const

Interface Category:

API.

Purpose:

Compares TThreadHandles for equality.

Calling Context:

Called by the collection classes.

Parameters:

const TThreadHandle & right -The object to which this is being compared.

Return Value:

Returns kEqual if the two TThreadHandles represent the same memory object. Returns kNotEqual otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TThreadHandle::Hash

virtual HashResult Hash () const

Interface Category:

API.

Purpose:

Returns a hash value.

Calling Context:

Called whenever a hash value is required for the object.

Parameters:

Takes no parameters.

Return Value:

Returns a HashResult.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TThreadHandle::IsSelf

virtual bool IsSelf () const

Interface Category:

API.

Purpose:

Determines if the TThreadHandle object represents the currently executing thread.

Calling Context:

Called to determine what thread the TThreadHandle represents.

Parameters:

Takes no parameters.

Return Value:

Returns true if the TThreadHandle object represents the currently executing thread. Otherwise, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TThreadHandle::Exists

virtual bool Exists () const

Interface Category:

API.

Purpose:

Determines if the thread represented by the TThreadHandle object exists.

Calling Context:

Called to determine the state of the thread represented by the TThreadHandle instance.

Parameters:

Takes no parameters.

Return Value:

Returns true if the thread represented by the TThreadHandle object exists. Otherwise, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TThreadHandle::PrintableRepresentation

virtual void PrintableRepresentation (TSimpleUnicodeArray & fillin) const

Interface Category:

API.

Purpose:

Returns a human-readable representation of the TThreadHandle.

Calling Context:

Called to obtain a readable representation of the TThreadHandle. This is useful for debugging.

Parameters:

TSimpleUnicodeArray &fillin -A reference to a TSimpleUnicodeArray object that will be filled in with a printable representation of the TThreadHandle.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Objects that compare equal using operator== return the same printable representation. If no such representation exists, a null TSimpleUnicodeArray object is returned. The representation can be platform and/or address-space dependent. That is, objects that exist in different address spaces and that might compare equal if they were in the same address space are not guaranteed to have identical printable representations. This function is intended for debugging use only. No guarantees are made as to the informational content of the printable representation.

Member Function: TThreadHandle::Kill

virtual void Kill ()

Interface Category:

API.

Purpose:

Terminates the thread.

Calling Context:

Called to control the execution of the thread represented by the TThreadHandle instance.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TThreadException(TThreadException::kBadThread) if the TThreadHandle does not represent an existing thread.

Concurrency:

Not multithread safe.

Other Considerations:

This call should only be used in special circumstances because no user-level clean-up code gets to run. CancelWaitAndPostException or your own ad hoc protocol should be used to provide safe termination.

Member Function: TThreadHandle::CopyThreadSchedule

TThreadSchedule * CopyThreadSchedule () const

Interface Category:

API.

Purpose:

Returns a copy of the thread's schedule object.

Calling Context:

Called to query the state of the thread represented by the TThreadHandle instance.

Parameters:

Takes no parameters.

Return Value:

A pointer to a copy of the thread's TThreadSchedule object.

Exceptions:

Throws TThreadException(TThreadException::kBadThread) if the TThreadHandle does not represent an existing thread.

Concurrency:

Not multithread safe.

Other Considerations:

Allocates memory for the TThreadSchedule object that must be disposed of by the caller.

Member Function: TThreadHandle::SetThreadSchedule

virtual void SetThreadSchedule (const TThreadSchedule & newSchedule)

Interface Category:

API.

Purpose:

Sets the thread's schedule object.

Calling Context:

Called to control the execution of the thread represented by the TThreadHandle instance.

Parameters:

const TThreadSchedule & newSchedule -A schedule object representing the new scheduling data that should be used for the thread.

Return Value:

None.

Exceptions:

Throws TThreadException(TThreadException::kBadThread) if the TThreadHandle does not represent an existing thread.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TThreadHandle::CancelWaitAndPostException

virtual void CancelWaitAndPostException () const

Interface Category:

API.

Purpose:

Causes an exception to be thrown in the thread.

Calling Context:

Called to control the execution of the thread represented by the TThreadHandle instance.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TThreadException(TThreadException::kBadThread) if the TThreadHandle does not represent an existing thread.

Concurrency:

Not multithread safe.

Other Considerations:

Causes any blocking kernel call being executed in the thread to be unblocked and a TCancelWaitException(TCancelWaitException::kWaitAborted) to be thrown. The thread that receives the TCancelWaitException should do an orderly terminate. This member function is preferred to Kill except in special circumstance because it allows the thread to clean up before terminating itself.

Member Function: TThreadHandle::CheckForPendingCancel

static void CheckForPendingCancel ()

Interface Category:

API.

Purpose:

Throws a TCancelWaitException if someone has executed a CancelWaitAndPostException for the thread.

Calling Context:

Called to receive any pending cancels that might not have been seen.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TCancelWaitException(TCancelWaitException::kWaitAborted) if there is a pending CancelWaitAndPostException for the thread.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TThreadHandle::ClearPendingCancel

static void ClearPendingCancel ()

Interface Category:

API.

Purpose:

Clears pending cancels posted to the thread.

Calling Context:

Called to clear pending cancels for the thread.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This call should only be used in special circumstances because it will possibly cause the client thread to ignore a pending cancel signal.

Member Function: TThreadHandle::WaitForDeathOf

virtual void WaitForDeathOf () const

Interface Category:

API.

Purpose:

Waits for the thread to die.

Calling Context:

Called to perform a death watch on the thread.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function does not throw an exception if the thread represented by the TThreadHandle is non-existent.

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