Class: TViewHandle

Declaration: ViewHandle.h

Taxonomy Categories:

Member Functions:

TViewHandle
~TViewHandle
operator=
Hash
GetView
PostRequest
UsesRequestProcessor
ExecuteRequest
operator<<=
operator>>=

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

TViewSurrogate

Purpose:

TViewHandle's instances are safe references to views and can be used from another thread. A TViewHandle tracks when its associated view is deleted. The member function GetView returns the view associated with the TViewHandle or returns NIL if the associated view has been deleted.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Member Function: TViewHandle::TViewHandle

TViewHandle (const TViewHandle &)
TViewHandle (const TView &)
TViewHandle ()
TViewHandle (TViewConnection *)

Interface Category:

API.

Purpose:

Copy constructor. The current implementation uses a reference counted hidden master scheme.
Constructs a TViewHandle from an existing view instance. This function is typically called by end users.
Default constructor.
Called internally only! Do not call.

Calling Context:

Called to copy an object.
Called to construct a new TViewHandle from a TView instance.
Called by the stream-in operators.
Called internally by the view system. Do not call.

Parameters:

const TViewHandle & -The object to be copied.
const TView & -The view that the new view handle should reference.
Takes no parameters.
TViewConnection * -Internal data type.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TViewHandle::~TViewHandle

virtual ~ TViewHandle ()

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:

Multithread safe.

Other Considerations:

None.

Member Function: TViewHandle::operator=

TViewHandle & operator =(const TViewHandle &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function by using the operator in an assignment statement.

Parameters:

const TViewHandle & -The object to be copied.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TViewHandle::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Overrides the inherited MCollectible function.

Calling Context:

Same as MCollectible function.

Parameters:

Takes no parameters.

Return Value:

Returns the numeric value of the hash.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TViewHandle::GetView

virtual TView * GetView () const

Interface Category:

API.

Purpose:

Returns the view associated with this view handle, or NIL if the view has been deleted.

Calling Context:

Called to get the view associated with this handle. This function should be called in an environment where the view cannot be deleted between the time this member function is called and when the returned view is used.

Parameters:

Takes no parameters.

Return Value:

Returns the view associated with this handle, or NIL if the view has been deleted.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This function should only be called in the viewÕs thread; otherwise, the result is unpredictable and potentially invalid.

Member Function: TViewHandle::PostRequest

virtual void PostRequest (TRequest * requestToAdopt)

Interface Category:

API.

Purpose:

Posts a request to the queue that is associated with this handle's view.

Calling Context:

Call this function directly.

Parameters:

TRequest * requestToAdopt -The adopted instance of TRequest to be posted to the queue.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This function executes (posts a request) and returns immediately.

Member Function: TViewHandle::UsesRequestProcessor

virtual bool UsesRequestProcessor (const TRequestProcessor &)

Interface Category:

API.

Purpose:

UsesRequestProcessor is a predicate function which determines if the request processor (request queue) that is associated with the view is the same as the given request processor. This function can be used to determine if the request is coming from the same thread as the view, in which case doing an ExecuteRequest operation will deadlock.

Calling Context:

Call this function directly.

Parameters:

const TRequestProcessor & -The request processor for the current thread.

Return Value:

Returns true if the given request processor is the same as the request processor that is associated with this handle's view. If the view has been deleted, it returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TViewHandle::ExecuteRequest

virtual void ExecuteRequest (TRequestComputation &)

Interface Category:

API.

Purpose:

Executes a synchronous request, blocking and waiting for the return. Typically, this function is used to execute a request that returns a value. It can also be used for operations that must be done synchronously.

Calling Context:

Called from outside of the thread that owns the view. If it is called from within the thread that owns the view, a deadlock will occur. It is the responsibility of the caller to check this before invoking the function.

Parameters:

TRequestComputation & -The request (a functor) to execute.

Return Value:

None.

Exceptions:

Throws a TViewHandleException if the view associated with this handle has been deleted.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TViewHandle::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 to which the object stream itself in.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TViewHandle::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 to which the object streams itself out.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

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