Class: TShutdownServerHandle

Declaration: Shutdown.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MRemoteCaller

Inherited By:

None.

Purpose:

Provides the client interface to the system shutdown server.

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: TShutdownServerHandle::TShutdownServerHandle

TShutdownServerHandle ()

Interface Category:

API.

Purpose:

Default constructor.

Calling Context:

Called by clients to construct the shutdown server handle.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::~TShutdownServerHandle

virtual ~ TShutdownServerHandle ()

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: TShutdownServerHandle::InitiateShutdown

virtual void InitiateShutdown ()

Interface Category:

API.

Purpose:

Originates a system shutdown. Calling this member function sets the system-wide shutdown process in motion. The call does not block while the shutdown is in progress, but instead returns immediately.

Calling Context:

Called by the Workspace in response to a user request for a shutdown. Can also be called by any client to invoke an orderly shutdown.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TShutdownException if a shutdown is already in progress.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::InitiateShutdownAndRestart

virtual void InitiateShutdownAndRestart ()

Interface Category:

API.

Purpose:

Originates a system shutdown and restarts the CommonPoint system. Calling this member function sets the system wide shutdown process in motion. The call does not block while shutdown is in progress, but instead returns immediately.

Calling Context:

Called by the Workspace in response to a user request to initiate shutdown. Can be called by any client to invoke a restart of the CommonPoint environment.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TShutdownException if a shutdown is already in progress.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::IsShutdownInProgress

virtual bool IsShutdownInProgress ()

Interface Category:

API.

Purpose:

Determines if the system shutdown is currently in progress.

Calling Context:

Called by clients at any time to determine if the system is in the process of being shut down.

Parameters:

Takes no parameters.

Return Value:

Returns true if the system is being shut down. Returns false if the system is operating normally.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::CancelPendingShutdown

virtual void CancelPendingShutdown ()

Interface Category:

API.

Purpose:

Cancels a pending shutdown.

Calling Context:

Called anytime before any actual shutdowns have occurred. If this member function is called when it is too late for shutdown to be canceled, an exception is thrown. Clients will not normally need to use this member function; cancellation is usually performed by the system shutdown service as a result of a kCancelShutdown return value from one of the verification member functions of a shutdown handler.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TShutdownException if no shutdown is in progress or if shutdown has progressed too far to be canceled.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::Register

virtual void Register (const TShutdownHandler & theHandler)
virtual void Register (const TShutdownHandler & theHandler, const TShutdownHandlerName & handlerName)

Interface Category:

API.

Purpose:

Activates an anonymous handler for shutdown processing.
Activates a handler and associates it with the specified name.

Calling Context:

Called by clients to register a shutdown handler anonymously for participation in the system shutdown process.
Called by clients to register a named shutdown handler for participation in the system shutdown process.

Parameters:

const TShutdownHandler & theHandler -The handler to be registered.
const TShutdownHandler & theHandler -The handler to be registered.
const TShutdownHandlerName & handlerName -The name to associate with this handler.

Return Value:

None.

Exceptions:

Throws TShutdownException if the handler is already registered or if another handler is already registered under the same name.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::DeRegister

virtual void DeRegister (const TShutdownHandler & theHandler)

Interface Category:

API.

Purpose:

Deactivates a shutdown handler. Handlers that are not registered are not included in the system shutdown process.

Calling Context:

Called automatically to deactivate a shutdown handler during shutdown handler destruction.

Parameters:

const TShutdownHandler & theHandler -The handler to be deregistered.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::IsRegistered

virtual bool IsRegistered (const TShutdownHandlerIdentifier & handlerIdentifier) const
virtual bool IsRegistered (const TShutdownHandler & theHandler) const

Interface Category:

API.

Purpose:

Determines if the handler represented by the identifier is registered for shutdown processing.
Determines if the referenced handler is registered for shutdown processing.

Calling Context:

Called to determine if a handler for which you possess an identifier is registered.
Called to determine if a handler for which you have direct access is registered.

Parameters:

const TShutdownHandlerIdentifier & handlerIdentifier -The identifier for the handler to check.
const TShutdownHandler & theHandler -The shutdown handler to check.

Return Value:

Returns true if the handler is registered.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::GetShutdownHandlerIdentifier

virtual void GetShutdownHandlerIdentifier (const TShutdownHandler & theHandler, TShutdownHandlerIdentifier & returnID) const

Interface Category:

API.

Purpose:

Creates a shutdown handler identifier for the specified shutdown handler.

Calling Context:

Called to create a shutdown handler identifier for a shutdown handler for which you have direct access. This is useful if you want to create an identifier for an anonymous handler to pass to a client that does not have direct access to the shutdown handler itself.

Parameters:

const TShutdownHandler & theHandler -The shutdown handler to be identified.
TShutdownHandlerIdentifier & returnID -The setup to represent the specified shutdown handler.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::GetName

virtual void GetName (const TShutdownHandlerIdentifier & handlerID, TShutdownHandlerName & theHandlerName) const

Interface Category:

API.

Purpose:

Returns the registered name of the identified shutdown handler. If the specified handler is registered anonymously, or if the handler is not registered, then an empty string is returned.

Calling Context:

Called directly to find out the registered name of a shutdown handler.

Parameters:

const TShutdownHandlerIdentifier & handlerID -The identifier representing the handler.
TShutdownHandlerName & theHandlerName -The registered name returned here or an empty string.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::ShutDownWith

virtual void ShutDownWith (const TShutdownHandler & theHandler, const TShutdownHandlerIdentifier & withThisHandler)
virtual void ShutDownWith (const TShutdownHandler & theHandler, const TShutdownHandlerName & withThisHandlerName)

Interface Category:

API.

Purpose:

Shuts down at essentially the same time as a particular handler. This member function is most commonly used with one of the predefined shutdown handler name constants that actually define the shutdown stages. Note that shutdowns are not actually processed in parallel, but the handler is grouped with the other handlers registered to shutdown with the specified With handler.

With handler specified by identifier.
With handler specified by name.

Calling Context:

Called before or after shutdown handler registration to establish position in the shutdown order. Note that only one With handler is allowed for any one shutdown handler.

Parameters:

const TShutdownHandler & theHandler -The shutdown handler.
const TShutdownHandlerIdentifier & withThisHandler -The identifier for the handler to be grouped with.
const TShutdownHandler & theHandler -The shutdown handler.
const TShutdownHandlerName & withThisHandlerName -The name of the handler or predefined stage to be grouped with.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::ShutDownBefore

virtual void ShutDownBefore (const TShutdownHandler & theHandler, const TShutdownHandlerIdentifier & beforeThisHandler)
virtual void ShutDownBefore (const TShutdownHandler & theHandler, const TShutdownHandlerName & beforeThisHandlerName)
virtual void ShutDownBefore (const TShutdownHandler & theHandler, const TSequenceOf < TShutdownHandlerIdentifier > & dependencyList)

Interface Category:

API.

Purpose:

Shuts down before the specified handler. This member function allows the specification of a dependency of one handler on the services to be represented by another.

Dependency specified by identifier.
Dependency specified by registration name.
List of identifiers added as dependencies.

Calling Context:

Called as many times as necessary to identify dependencies. Duplicate identifiers for the same handler are ignored.

Parameters:

const TShutdownHandler & theHandler -The shutdown handler.
const TShutdownHandlerIdentifier & beforeThisHandler -The identifier theHandler is dependent on.
const TShutdownHandler & theHandler -The shutdown handler.
const TShutdownHandlerName & beforeThisHandlerName -The registration name for the shutdown handler theHandler is dependent on.
const TShutdownHandler & theHandler -The shutdown handler.
const TSequenceOf < TShutdownHandlerIdentifier > & dependencyList -The list of shutdown handler identifiers to be included as dependencies.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::GetDependencyList

virtual void GetDependencyList (const TShutdownHandler & theHandler, TSequenceOf < TShutdownHandlerIdentifier > & dependencyList) const

Interface Category:

API.

Purpose:

Returns the list of dependencies for the specified shutdown handler.

Calling Context:

Called to check dependency list. You can call GetDependencyList, make changes to the list, call RemoveAllDependencies, and finally call ShutDownBefore with the modified list to make large-scale changes to the dependency specifications for a particular shutdown handler.

Parameters:

const TShutdownHandler & theHandler -The shutdown handler.
TSequenceOf < TShutdownHandlerIdentifier > & dependencyList -The sequence to be filled in with shutdown handler identifiers.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::RemoveDependency

virtual void RemoveDependency (const TShutdownHandler & theHandler, const TShutdownHandlerIdentifier & dependencyToRemove)

Interface Category:

API.

Purpose:

Removes the specified dependency from the shutdown handler.

Calling Context:

Called to remove an individual dependency.

Parameters:

const TShutdownHandler & theHandler -The shutdown handler.
const TShutdownHandlerIdentifier & dependencyToRemove -The identifier for the handler upon which theHandler no longer depends.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::RemoveAllDependencies

virtual void RemoveAllDependencies (const TShutdownHandler & theHandler)

Interface Category:

API.

Purpose:

Removes all dependency specifications for a shutdown handler.

Calling Context:

Called by clients to clear all dependency specification, usually in preparation for respecifying dependencies due to some state change in the service the shutdown handler represents.

Parameters:

const TShutdownHandler & theHandler -The handler from which to remove dependencies.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::ClearAllOrderingHints

virtual void ClearAllOrderingHints (const TShutdownHandler & theHandler)

Interface Category:

API.

Purpose:

Clears all ordering information for the specified shutdown handler. Removes dependencies and any With specification.

Calling Context:

Called by clients in preparation for respecifying ordering requirements for a shutdown handler.

Parameters:

const TShutdownHandler & theHandler -The shutdown handler.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::NeedMoreTime

virtual void NeedMoreTime (const TShutdownHandler & theHandler)

Interface Category:

API.

Purpose:

Resets the time-out counter for the current shutdown processing member function. This causes the system shutdown service to allow the shutdown handler to process for another time-out period.

Calling Context:

Called from the shutdown handler as needed. Each call to NeedMoreTime results in the reset of the time allowed for the handler to process the current member function. Calls to this member function are only useful when the specified handler is actually processing in VerifyShutdown, PrepareForShutdown, or CompleteShutdown. This member function has no effect if called at any other time.

Parameters:

const TShutdownHandler & theHandler -The shutdown handler to receive more processing time.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::GetTimeOutForVerifyShutdown

virtual ShutdownTimeOutValueInSeconds GetTimeOutForVerifyShutdown (const TShutdownHandler & theHandler) const

Interface Category:

API.

Purpose:

Returns the number of seconds the specified handler is allowed to process before returning from VerifyShutdown before being timed out.

Calling Context:

Called directly to obtain the number of seconds a shutdown handler is allowed to process.

Parameters:

const TShutdownHandler & theHandler -The shutdown handler.

Return Value:

The number of seconds the handler is allowed to process the VerifyShutdown member function.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::GetTimeOutForPrepareForShutdown

virtual ShutdownTimeOutValueInSeconds GetTimeOutForPrepareForShutdown (const TShutdownHandler & theHandler) const

Interface Category:

API.

Purpose:

Returns the number of seconds the specified handler is allowed to process before returning from PrepareForShutdown before being timed out.

Calling Context:

Called directly to obtain the number of seconds a shutdown handler is allowed to process.

Parameters:

const TShutdownHandler & theHandler -The shutdown handler.

Return Value:

The number of seconds the handler is allowed to process the PrepareForShutdown member function.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::GetTimeOutForCompleteShutdown

virtual ShutdownTimeOutValueInSeconds GetTimeOutForCompleteShutdown (const TShutdownHandler & theHandler) const

Interface Category:

API.

Purpose:

Returns the number of seconds the specified handler is allowed to process before returning from CompleteShutdown before being timed out.

Calling Context:

Called directly to obtain the number of seconds a shutdown handler is allowed to process.

Parameters:

const TShutdownHandler & theHandler -The shutdown handler.

Return Value:

The number of seconds the handler is allowed to process the CompleteShutdown member function.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::SetTimeOutForVerifyShutdown

virtual void SetTimeOutForVerifyShutdown (const TShutdownHandler & theHandler, const ShutdownTimeOutValueInSeconds seconds)

Interface Category:

API.

Purpose:

Sets the number of seconds the specified handler is allowed to process before returning from VerifyShutdown before being timed out.

Calling Context:

Called directly to adjust the number of seconds a shutdown handler is allowed to process. For most clients, the system default should be sufficient and use of this member function is unnecessary. The system default time-out period value is defined by kDefaultShutdownTimeoutValue and is currently 45 seconds.

Parameters:

const TShutdownHandler & theHandler -The shutdown handler.
const ShutdownTimeOutValueInSeconds seconds -The number of seconds before time out.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::SetTimeOutForPrepareForShutdown

virtual void SetTimeOutForPrepareForShutdown (const TShutdownHandler & theHandler, const ShutdownTimeOutValueInSeconds seconds)

Interface Category:

API.

Purpose:

Sets the number of seconds the specified handler is allowed to process before returning from PrepareForShutdown before being timed out.

Calling Context:

Parameters:

const TShutdownHandler & theHandler -The shutdown handler.
const ShutdownTimeOutValueInSeconds seconds -The number of seconds before time out.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TShutdownServerHandle::SetTimeOutForCompleteShutdown

virtual void SetTimeOutForCompleteShutdown (const TShutdownHandler & theHandler, const ShutdownTimeOutValueInSeconds seconds)

Interface Category:

API.

Purpose:

Sets the number of seconds the specified handler is allowed to process before returning from CompleteShutdown before being timed out.

Calling Context:

Parameters:

const TShutdownHandler & theHandler -The shutdown handler.
const ShutdownTimeOutValueInSeconds seconds -The number of seconds before time out.

Return Value:

None.

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.