Class: TDispatcherThread

Declaration: DispatcherThread.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

TDispatcherThread is a class that provides a convenient and easy-to-use thread object for receiving RPC requests. TDispatcherThread adopts a ReceiverStream and a MRemoteDispatcher for receiving requests from the caller and dispatching the requests.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Derived classes are not supported in this release.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TDispatcherThread::TDispatcherThread

TDispatcherThread (TReqReceiverStream * adoptStream, MRemoteDispatcher * adoptDispatcher)

Interface Category:

API.

Purpose:

Creates a TDispatcherThread object with the specified TRequestReceiverStream and MRemoteDispatcher.

Calling Context:

Called to create a TDispatcherThread with a specific TRequestReceiverStream and MRemoteDispatcher. Call this function directly.

Parameters:

TReqReceiverStream * adoptStream -The stream to use for receiving requests.
MRemoteDispatcher * adoptDispatcher -The dispatcher to use to dispatch requests that are received.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDispatcherThread::~TDispatcherThread

virtual ~ TDispatcherThread ()

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:

None.

Member Function: TDispatcherThread::Start

virtual void Start ()

Interface Category:

API.

Purpose:

Starts a new thread for the processing loop of receiving and dispatching requests. Start should be called at most once in each TDispatcherThread.

Calling Context:

Called to start the new thread. Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Repeated calls to Start have no effect. After both SetAutomaticallyDestroyed(true) and Start are called, accessing the TDispatcherThread is undefined. (Heap corruption can occur if it is accessed.) These 2 calls combined perform like a request to adopt the TDispatcherThread.

Member Function: TDispatcherThread::SetAutomaticallyDestroyed

virtual void SetAutomaticallyDestroyed (bool =true)

Interface Category:

API.

Purpose:

Controls whether this object gets destroyed when dispatching ends.

Calling Context:

Called to enable or disable the automatic destruction of this thread. Call this function directly.

Parameters:

bool =true -If set to true, automatic destruction is enabled.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Before Start is called, SetAutomaticallyDestroyed can be called just like setting an attribute. If when Start is called, this TDispatcherThread is to be automatically destroyed, then further access of the TDispatcherThread is undefined. If when Start is called, this TDispatcherThread is not to be automatically destroyed, a later SetAutomaticallyDestroyed(true) call causes the TDispatcherThread to be destroyed automatically. TDipsatcherThread is initialized to be NOT auto-destroyed.

Member Function: TDispatcherThread::WaitForDeath

virtual void WaitForDeath ()

Interface Category:

API.

Purpose:

Blocks the caller until the dispatching thread terminates. Multiple threads may safely execute WaitForDeath concurrently.

Calling Context:

Called to wait for the dispatching thread to finish dispatching requests. Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

WaitForDeath is a no-op if it's called before Start has been executed.

Member Function: TDispatcherThread::CancelWaitAndPostException

virtual void CancelWaitAndPostException ()

Interface Category:

API.

Purpose:

Causes an exception to be thrown in the dispatching thread started by the Start member function. Ordinarily, calling this member function causes the thread of the dispatching loop to release all its resources and terminate. However, the thread may choose to catch the exception and do other processing instead.

Calling Context:

Called to cause an exception to be thrown in the dispatching thread. Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

This member function itself throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

CancelWaitAndPostException is a no-op if it's called before Start has been executed. Currently, this member function is a no-op due to defect in Kernel Services.

Member Function: TDispatcherThread::Kill

virtual void Kill ()

Interface Category:

API.

Purpose:

Immediately ceases execution of the dispatching thread started by the Start member function. Any resources that were held by the thread of the dispatching loop are not released. Kill does not delete this TDispatcherThread, even if automatic destruction was previously set by a call to SetAutomaticallyDestroyed.

Calling Context:

Called to terminate the execution of the dispatching thread. Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Kill is a no-op if it's called before Start has been executed.

Member Function: TDispatcherThread::Dispatch

static void Dispatch (TReqReceiverStream &, MRemoteDispatcher &)
virtual void Dispatch ()

Interface Category:

API.

Purpose:

Begins receiving requests from the stream and passing them on to the dispatcher. This is a static member function. It is used when the user doesn't want a new thread to be created for the dispatching loop.
Begins receiving and dispatching requests, if the stream and dispatcher are not NIL. This member function is used by TDispatcherThread when Start is called.

Calling Context:

Called to begin receiving and dispatching requests. Call this function directly.
Called to begin receiving and dispatching requests if the TRequestReceiverStream and MRemoteDispatcher are not NIL. It is used by Remote Object Call Services and (future) derived classes.

Parameters:

TReqReceiverStream & -The stream to use for receiving requests.
MRemoteDispatcher & adoptDispatcher -The dispatcher to handle requests that are received.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, catches all exceptions except TCancelWaitException raised in the dispatching loop, passes all other exceptions through.
Throws no exceptions, catches TCancelWaitException raised in the dispatching loop, passes all other exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

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