Class: TTaligentTaskHandle

Declaration: TaligentTaskHandle.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TTaskHandle

Inherited By:

None.

Purpose:

TTaligentTaskHandle is a wrapper for a task. A task consists of an address space and a collection of one or more cooperating threads. Destroying a TTaligentTaskHandle object does not destroy the task it represents. New tasks can be created by calling specific forms of the TTaligentTaskHandle constructor. TTaligentTaskHandle can be used to query the status of a task and control its state.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Do not derive any classes from TTaligentTaskHandle.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

TTaligentTaskHandle inherits its behavior for operator== from TTaskHandle. The class TTaskHandle specifies that two objects that are is-a TTaskHandle, either directly or indirectly, return true on operator== if and only if both objects refer to the same underlying task. For example, consider the following code fragment: TTaskHandle me1(TTaskHandle::kUseCurrentThread); // get current task TTaligentTaskHandle me2(TTaligentTaskHandle::kUseCurrentTask): // get current task if (me1 ==me2) printf("Same task, in spite of different representations!\n"); if (me2 ==me1) printf("Same task, in spite of different representations!\n"); TTaligentTaskHandle inherits its behavior for Hash, Exists, Kill, and WaitForDeathOf from TTaskHandle.

Member Function: TTaligentTaskHandle::~TTaligentTaskHandle

virtual ~TTaligentTaskHandle()

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:

None.

Member Function: TTaligentTaskHandle::GetTaskSet

static void GetTaskSet (TCollectionOf < TTaligentTaskHandle > & where)

Interface Category:

API.

Purpose:

Fills in a collection of all tasks currently on the system. It is the callers responsibility to free the allocated memory.

Calling Context:

Call this member function to obtain all the TTaligentTaskHandle's in the current sess ion.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

W A R N I N G ! : Caller is responsible for deleting objects returned in co llection!!

Member Function: TTaligentTaskHandle::CreateThread

virtual TThreadHandle CreateThread (const TThreadProgram & whatToRun)

Interface Category:

API.

Purpose:

Create a new thread in the task. Execute the specified TThreadProgram in that task.

Calling Context:

This member function is used to create a thread in another address space.

Parameters:

Return Value:

Return the TThreadHandle of the thread executing in the target task.

Exceptions:

Throws any exceptions caused by Prepare member function in whatToRun.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTaligentTaskHandle::operator>>=

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

Interface Category:

API.

Purpose:

Stream out a TTaligentTaskHandle Object to a TMessageStream.

Calling Context:

Called when the task handle needs to be written to a stream.

Parameters:

Return Value:

Return the output stream.

Exceptions:

Throws exception if there is a problem with the stream. Throws an exception if you write to a stream class that doesn't support stre aming of tasks.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTaligentTaskHandle::operator<<=

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

Interface Category:

API.

Purpose:

Stream in a TTaligentTaskHandle object to a TMessageStream.

Calling Context:

Called when the task handle needs to be read from a stream.

Parameters:

Return Value:

Return the input stream.

Exceptions:

Throws exception if there is a problem with the stream. Throws an exception if you read from a stream class that doesn't support str eaming of tasks.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTaligentTaskHandle::operator=

TTaligentTaskHandle & operator =(const TTaligentTaskHandle & sourceHandle)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this

Parameters:

Return Value:

Reference to this task.

Exceptions:

Passes through exceptions from assignment operator on base class TTaskHandle. An exception may be thrown if the task no longer exists.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTaligentTaskHandle::TTaligentTaskHandle

  1. TTaligentTaskHandle (const TThreadProgram & whatToRun)
  2. TTaligentTaskHandle (EExecutionTask)
  3. TTaligentTaskHandle (const TTaligentTaskHandle & aTask)
  4. TTaligentTaskHandle ()

Interface Category:

API.

Purpose:

  1. Creates a new thread in the task. Executes the specified TThreadProgram in that task.
  2. Wraps task of currently executing thread. Use the following enum: enum EExecutionTask { kUseCurrentTask };
  3. Makes a copy of another TTaligentTaskHandle.
  4. Default constructor for streaming into.

Calling Context:

  1. This member function is used to create a thread in another address space.
  2. Use this constructor when you want to obtain a handle to the current task.
  3. Use this copy constructor to make copy of a task handle.
  4. Call this prior to stream in.

Parameters:

Return Value:

#1 Returns the TThreadHandle of the thread executing in the target task. #2-4 - None.

Exceptions:

Passes through exceptions from copy constructor on base class TTaskHandle. An exception may be thrown if the task no longer exists.

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.