Declaration: Task.h
Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
None.
Inherited By:
None.
Purpose:
TTaskHandle is a concrete class that represents a task.
Instantiation:
Allocate on the heap or the stack.
Deriving Classes:
Derived classes implement TaskHandles that follow specific runtime conventions (for example, TTaligentTaskHandle). Derived classes can override virtual member functions of TaskHandle, but most likely will only supplement the member functions provided.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
Other Considerations:
None.
- TTaskHandle (EExecutionThread)
- TTaskHandle (const TTaskHandle & aTask)
- TTaskHandle ()
Interface Category:
API.
Purpose:
- Constructor. (API.)
- Copy constructor. (API.)
- Default constructor. (API.)
Calling Context:
- Called to create a TTaskHandle that represents task in which the current thread is executing.
- Called to copy an object.
- Called by the stream-in operators.
Parameters:
- EExecutionThread -An enumeration option. kUseCurrentThread is the only possible value.
- const TTaskHandle & aTask -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.
virtual ~ TTaskHandle ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This member function only destroys the TTaskHandle instance and not the kernel entity it represents.
Member Function: TTaskHandle::operator=
TTaskHandle & operator =(const TTaskHandle & source)
Interface Category:
API.
Purpose:
Assignment operator.
Calling Context:
Called when an object is assigned to another compatible object.
Parameters:
- const TTaskHandle & source -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: TTaskHandle::operator==
bool operator ==(const TTaskHandle & toWhat) const
Interface Category:
API.
Purpose:
Compares TTaskHandles for equality.
Calling Context:
Called to determine when two TTaskHandle represent the same memory object.
Parameters:
- const TTaskHandle & toWhat -The object on the right-hand side of the equality comparator.
Return Value:
Returns true if the two TTaskHandles 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: TTaskHandle::operator!=
bool operator != (const TTaskHandle & toWhat) const
Interface Category:
API.
Purpose:
Compares TTaskHandles for inequality.
Calling Context:
Called to determine when two TTaskHandles do not represent the same memory object.
Parameters:
- const TTaskHandle & toWhat -The object on the right-hand side of the inequality comparator.
Return Value:
Returns true if the two TTaskHandles 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: TTaskHandle::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: TTaskHandle::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: TTaskHandle::IsEqual
virtual EComparisonResult IsEqual (const TTaskHandle & right) const
Interface Category:
API.
Purpose:
Compares TTaskHandles for equality.
Calling Context:
Called by the collection classes.
Parameters:
- const TTaskHandle & right -The object to which this is being compared.
Return Value:
Returns kEqual if the two TTaskHandles 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: TTaskHandle::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:
Return Value:
Returns a HashResult.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTaskHandle::IsSelf
virtual bool IsSelf () const
Interface Category:
API.
Purpose:
Determines if the TTaskHandle object represents the task in which the current thread is executing.
Calling Context:
Called to determine what task the TTaskHandle represents.
Parameters:
Return Value:
Returns true if the TTaskHandle object represents the currently task. Otherwise, returns false.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTaskHandle::Exists
virtual bool Exists () const
Interface Category:
API.
Purpose:
Determines if the task represented by the TTaskHandle object exists.
Calling Context:
Called to determine the state of the task represented by the TTaskHandle instance.
Parameters:
Return Value:
Returns true if the task represented by the TTaskHandle object exists. Otherwise, returns false.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTaskHandle::PrintableRepresentation
virtual void PrintableRepresentation (TSimpleUnicodeArray & fillin) const
Interface Category:
API.
Purpose:
Returns a human-readable representation of the TTaskHandle.
Calling Context:
Called to obtain a readable representation of the TTaskHandle. This is useful for debugging.
Parameters:
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: TTaskHandle::Kill
virtual void Kill ()
Interface Category:
API.
Purpose:
Terminates the task.
Calling Context:
Called to control the execution of the thread represented by the TThreadHandle instance.
Parameters:
Return Value:
None.
Exceptions:
Throws TTaskException(TTaskException::kBadTask) if the TTaskHandle does not represent an existing task.
Concurrency:
Not multithread safe.
Other Considerations:
This call should only be used in special circumstances since 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: TTaskHandle::WaitForDeathOf
virtual void WaitForDeathOf () const
Interface Category:
API.
Purpose:
Waits for the task to die.
Calling Context:
Called to perform a death watch on the task.
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 task represented by the TTaskHandle is non-existent.
Member Function: TTaskHandle::GetThreadSet
virtual void GetThreadSet (TCollectionOf < TThreadHandle > & where) const
Interface Category:
API.
Purpose:
Returns a set of TThreadHandles for threads contained by this task.
Calling Context:
Called to query the state of the task.
Parameters:
Return Value:
None.
Exceptions:
Throws TTaskException(TTaskException::kBadTask) if the TTaskHandle does not represent an existing task.
Concurrency:
Not multithread safe.
Other Considerations:
It is the caller's responsibility to free the memory allocated for the TThreadHandles returned in the collection.
Member Function: TTaskHandle::IsMember
virtual bool IsMember (const TThreadHandle & aThread) const
Interface Category:
API.
Purpose:
Determines if a particular thread belongs to the task.
Calling Context:
Called to query the state of the task.
Parameters:
Return Value:
Returns true if the thread is contained in the task; otherwise, returns false.
Exceptions:
Throws TTaskException(TTaskException::kBadTask) if the TTaskHandle does not represent an existing task.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.