Class: TShutdownHandlerIdentifier

Declaration: Shutdown.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TAbstractShutdownHandlerIdentifier

Inherited By:

None.

Purpose:

Shutdown handlers are uniquely identified through TShutdownHandlerIdentifier objects. TShutdownHandlerIdentifier objects are used in areas of the shutdown service where handlers need to be specified, such as when shutdown ordering dependencies are enumerated. TShutdownHandlerIdentifier objects are concrete, lightweight, and streamable; however, they are only valid for the current system session, so they can't be streamed to deep freeze. There are two ways of obtaining a shutdown handler identifier for a specific handler: one is to ask the shutdown server to create an identifier for a specific handler directly, the other is to construct an identifier from a handler name. IDs for both anonymous and named handlers can be obtained from the shutdown server, as long as the caller has direct access to the shutdown handler, using the TShutdownServerHandle member function GetShutdownHandlerIdentifier. IDs for named handlers can be constructed using only the handler name. Shutdown handler identifiers are either valid or invalid. Valid identifiers refer to an active shutdown handler registered with the system shutdown service. Invalid identifiers do not represent an active handler. Identifiers can become invalid if the handler to which they refer terminates. Once the ShutDown member function of a handler has been called, all identifiers for that handler become invalid. The usage of invalid shutdown handler identifiers, for example, in calling out dependencies, is not restricted and will not result in exceptions, but invalid identifiers will be ignored when the shutdown service performs execution ordering calculations. This enables one beneficial feature. If an identifier is constructed with a well known handler name, but that handler has not yet been registered with the system shutdown service, the identifier is invalid. However, if the corresponding handler is later registered using the same well-known name, the identifier becomes valid at that point. This provides a means of dealing with the uncontrolled ordering of handler instantiation. For example, this allows the expression of a dependency on a handler without that handler having yet been created. If the named handler is never registered, then the dependency is simply ignored. Clients of shutdown might want to add an API to their frameworks to return the shutdown handler identifier that represents the shutdown handler for their service, component, or functional area. They might also want to establish a well-known name to be associated with their primary shutdown handler.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Do not derive.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TShutdownHandlerIdentifier::TShutdownHandlerIdentifier

TShutdownHandlerIdentifier (const TShutdownHandlerName & wellKnownHandlerName)
TShutdownHandlerIdentifier ()
TShutdownHandlerIdentifier (const TShutdownHandlerIdentifier & source)

Interface Category:

API.

Purpose:

Constructs an identifier representing a named shutdown handler.
Default constructor.
Copy constructor.

Calling Context:

Called by shutdown clients to create an identifier that refers to a named shutdown handler.
Called by the stream-in operators.
Called to copy an object.

Parameters:

const TShutdownHandlerName & wellKnownHandlerName -The registered shutdown handler name.
Takes no parameters.
const TShutdownHandlerIdentifier & source -The identifier to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownHandlerIdentifier::GetShutdownHandlerName

virtual void GetShutdownHandlerName (TShutdownHandlerName & theHandlerName) const

Interface Category:

API.

Purpose:

Returns the registered name of the shutdown handler represented by this identifier. If the handler corresponding to this identifier is not registered or was registered anonymously, then an empty string is returned.

Calling Context:

Called to allow clients to obtain the registered name of a shutdown handler. Seldom used.

Parameters:

TShutdownHandlerName &theHandlerName -Receives the shutdown handler name or an empty string if no names exists for the handler represented by this identifier.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

If the identifier was constructed with a handler name, then that handler name is always available using this member function, regardless of the registration state of the shutdown handler. If the identifier was constructed by the system shutdown service for a specific handler, then the returned name is the name under which that handler is registered, if any. If the handler is not registered or is registered as anonymous, then an empty string is returned.

Member Function: TShutdownHandlerIdentifier::operator=

TAbstractShutdownHandlerIdentifier & operator =(const TAbstractShutdownHandlerIdentifier & source)

Interface Category:

API.

Purpose:

Assignment. Makes the identifier on the left side of the equal sign refer to the same shutdown handler as the identifier on the right.

Calling Context:

Called as needed.

Parameters:

const TAbstractShutdownHandlerIdentifier & source -The identifier to copy.

Return Value:

The reference to this identifier.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownHandlerIdentifier::~TShutdownHandlerIdentifier

virtual ~ TShutdownHandlerIdentifier ()

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: TShutdownHandlerIdentifier::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

Called to generate a hash value.

Parameters:

Takes no parameters.

Return Value:

The numeric value of the hash.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownHandlerIdentifier::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: TShutdownHandlerIdentifier::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 from.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

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