Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
TAbstractShutdownHandler
Inherited By:
None.
Purpose:
Base class for all shutdown handlers. Clients derive TShutdownHandler to perform processing during system shutdown. Shutdown handlers receive control for preshutdown verification, shutdown preparation, and for shutdown completion.
TShutdownServerHandle provides member functions for making ordering suggestions for a particular TShutdownHandler. These ordering suggestions specify where in the system shutdown time line the handler should execute. Clients should use shutdown server handle member functions such as ShutDownBefore, to ensure that their shutdown dependencies are best accommodated. Handlers for which no ordering recommendations are made process based on a default ordering scheme employed by the system shutdown service, which currently amounts to last-in-first-out based on shutdown handler registration, but is subject to change.
A handler becomes active when it is registered with the system shutdown service (see TShutdownServerHandle). A handler is automatically deregistered with the system shutdown service when its destructor executes.
Shutdown handlers are identified by TShutdownHandlerIdentifier objects.
Handlers can be registered as anonymous or named. Named handlers can have a shutdown handler ID constructed to represent them from anywhere in the system through use of the handler name. Handler names are guaranteed to be unique. Anonymous handlers are can still be identified by shutdown handler IDs, but the ID for an anonymous handler must be obtained using a reference to the handler itself.
Instantiation:
Allocate on the heap or the stack.
Deriving Classes:
Derive TShutdownHandler to participate in the system shutdown process. Override the VerifyShutdown, VerifyShutdownWithUserInteraction, PrepareForShutdown, CompleteShutdown, and/or ShutdownCanceled member functions as appropriate.
Concurrency:
Not multithread safe.
When a shutdown handler is registered with the system shutdown server, a thread is created in the client's address space, which is used to dispatch member function calls to the shutdown handler. Thus, shutdown member functions such as VerifyShutdown, PrepareForShutdown, and CompleteShutdown execute in this thread set up by the system shutdown service. Clients are responsible for managing the resultant multithread concurrency issues. For example, if an otherwise single-threaded server provides a shutdown handler, the shutdown handler executes in a separate thread, concurrently with the service itself, therefore any client facilities used during shutdown processing must be multithread safe.
Resource Use:
Even though TShutdownHandler derived classes can be created on the stack, it should be noted that they are not lightweight objects. Registered handlers have a thread created for them in the client's address space and resources maintained by the shutdown service. A shutdown handler should be around for the life of the service it represents.
Other Considerations:
Timing out -The system shutdown service imposes a time-out mechanism on all of the shutdown handler processing member functions with the exception of VerifyShutdownWithUserInteraction. This is an effort towards preventing the system shutdown process from hanging indefinitely due to some unknown error condition.
Calls to the shutdown handler member functions VerifyShutdown, PrepareForShutdown, and CompleteShutdown are made synchronously, one handler at a time. Every TShutdownHandler object can set a separate time-out period value for each of these calls. These time-out values are set to system defaults when the shutdown handler is constructed. The system default time-out period value is defined by kDefaultShutdownTimeoutValue and is currently 45 seconds. Clients can modify the default values for their handler through TShutdownServerHandle member functions such as SetTimeOutForCompleteShutdown.
While handling one of the shutdown processing member functions, clients can also request more time by calling the TShutdownServerHandle member function NeedMoreTime. Every call to NeedMoreTime resets the time-out counter, allowing a member function additional time to process. It is the handler's responsibility to determine when it is about to time out, as the system shutdown service provides no means of notifying the shutdown handler that it is approaching time out.
If the handler does not return from one of the shutdown processing member functions within the specified time-out period for that handler and that member function, shutdown processing continues with the next handler. If a handler times out, it is allowed to continue processing. The system shutdown service makes a best effort to include handlers that have timed out in future shutdown processing, based on when the handler actually completes the last request and on the state of the shutdown process at that point.
Enabling clients to adjust their time-out period reopens the door for hanging the shutdown process, so time-out adjustment should be used judiciously. Most clients will find the system default time-out values sufficient. More common should be the use of NeedMoreTime, which lets the system shutdown service know the handler is still alive and processing. For example, a shutdown handler for network file systems might call NeedMoreTime between unmounts of each remotely mounted file system.
TShutdownHandler ()
Interface Category:
API.
Purpose:
Default constructor.
Calling Context:
Called by a derived class' constructors.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual ~ TShutdownHandler ()
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: TShutdownHandler::VerifyShutdown
virtual TAbstractShutdownHandler :: EVerifyShutdownResponse VerifyShutdown ()
Interface Category:
API.
Purpose:
Called for all handlers before any actual shutdown processing occurs. It can be overridden to check for important and uninterruptible operations in progress, for example, a disk format or a modem file transfer. This member function is not intended to save persistent state, nor to perform any other actual shutdown processing. Rather, it is a check to ensure that no critical operations are in progress, and a promise that no new critical operations will be initiated for the service area represented by this handler.
Handlers return an EVerifyShutdownResponse that defines three values: kContinueShutdown, kCancelShutdown, and kNeedUserInteraction. If kContinueShutdown is returned from the VerifyShutdown member function, the handler is stating that it currently has no operations in progress that necessitate the cancellation of shutdown, and further, it will henceforth disallow the initiation of any operation that might require shutdown to be canceled. Clients should continue all normal operations that do not violate the no cancellation promise.
The VerifyShutdown call to each handler is made synchronously. However, shutdown handler objects have time-out values for each of the shutdown processing member functions. If the handler does not return within the specified time-out period, shutdown processing continues with the next handler as if kContinueShutdown had been returned. The system shutdown service makes a best effort to include handlers that have timed out in future shutdown processing, based on when the handler actually completes the last request and the state of the shutdown process at that point. If a timed-out handler returns a value such as kCancelShutdown or kNeedUserInteraction, that request will be honored providing that shutdown has not progressed beyond the verification phase of the current stage.
Handlers can receive additional time by calling the TShutdownServerHandle member function NeedMoreTime.
Calling Context:
Called by the system shutdown service. VerifyShutdownWithUserInteraction is called in a thread in the client's address space created by the system shutdown service when the handler was registered. Clients are responsible for managing any resultant concurrency issues.
Parameters:
Return Value:
TAbstractShutdownHandler::EVerifyShutdownResponse -Returns kContinueShutdown to the shutdown process (don't cancel), kCancelShutdown to cancel this pending shutdown, or kNeedUserInteraction to suspend the shutdown for user interaction. The default response is kContinueShutdown. If a handler needs a significant or indefinite amount of time to verify whether or not shutdown should continue, then the handler immediately returns kNeedUserInteraction. If kNeedUserInteraction is returned, the system shutdown service suspends the shutdown, restores other shutdown handlers to normal processing, and calls the VerifyShutdownWithUserInteraction member function of this handler.
If kCancelShutdown is returned, the shutdown process is entirely aborted. Clients are responsible for notifying the user as to why a shutdown was canceled. To perform a polite cancellation of the shutdown, a handler should first return kNeedUserInteraction in response to VerifyShutdown. The system shutdown service then calls the handler's VerifyShutdownWithUserInteraction member function. In this member function, the handler displays a dialog that describes for the user why the shutdown process should be canceled. In many cases the user is given the option of either canceling the shutdown as suggested or forcing the continuation of shutdown. When the dialog is dismissed, the handler returns either kCancelShutdown or kContinueShutdown as appropriate.
If any handler returns kCancelShutdown from a verification member function, then all shutdown handlers who have had their VerifyShutdown member functions called now have their ShutdownCanceled member function called, so that they can resume normal processing.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
See class documentation for discussion of time-out related issues.
Member Function: TShutdownHandler::VerifyShutdownWithUserInteraction
virtual TAbstractShutdownHandler :: EVerifyShutdownResponse VerifyShutdownWithUserInteraction ()
Interface Category:
API.
Purpose:
Override this member function to perform extended shutdown verification. VerifyShutdownWithUserInteraction is intended to provide for shutdown verification that can take an indefinite period of time. For example, if a remote file transfer is in progress, a shutdown handler can use this member function to present the user with a dialog providing the option to either wait for the completion of the transfer before resuming the system shutdown, or to abort or interrupt the transfer and continue immediately with the shutdown.
This member function can also be used to present a dialog that suggests that the user reconsider the shutdown, for example, if a hard disk format is in process, or the system is in a nonbootable state.
Outright cancellation of a shutdown, without providing the user an option to force shutdown continuation should be employed sparingly, if at all. The user might need to shut down the system due to some error condition in the system itself, so you should, in general, always provide a means of forcing the continuation of a shutdown, even if this results in state being lost or other less-than-optimal consequences.
Calling Context:
This member function is called by the system shutdown service when kNeedUserInteraction is returned from the VerifyShutdown member function of this handler. At the point at which this member function is called, shutdown has been suspended, and other shutdown handlers have resumed normal processing. While this member function is processing, no new shutdown can be initiated. VerifyShutdownWithUserInteraction does not time out. The system shutdown process remains in a suspended state until the handler returns from VerifyShutdownWithUserInteraction, or until the shutdown handler is destructed. VerifyShutdownWithUserInteraction is called in a thread in the client's address space created by the system shutdown service when the handler was registered. Clients are responsible for managing any resultant concurrency issues.
Parameters:
Return Value:
TAbstractShutdownHandler::EVerifyShutdownResponse -Returns kContinueShutdown to the shutdown process (don't cancel), or kCancelShutdown to cancel the pending shutdown. If the handler returns kContinueShutdown, then the shutdown process essentially begins anew, with VerifyShutdown calls to each handler, including this one. If kCancelShutdown is returned, the shutdown process is aborted. If the handler returns kNeedUserInteraction, the system shutdown service simply turns around and calls VerifyShutdownWithUserInteraction again.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TShutdownHandler::PrepareForShutdown
virtual void PrepareForShutdown ()
Interface Category:
API.
Purpose:
Derived classes override this member function to handle shutdown preparation. The PrepareForShutdown member function is intended as the place where persistent state is saved. Clients should be ready to have their CompleteShutdown member function called anytime after they have returned from PrepareForShutdown. This might involve, for example, flushing all operations to disk once PrepareForShutdown has been called.
Upon returning from PrepareForShutdown, clients should continue to function and process requests, in as normal a fashion as possible, but should be prepared to loose any service they depend upon without publicly complaining. What being prepared for shutdown really means is, "I am ready to have the plug pulled, but I'll hang around to help others get ready."
The PrepareForShutdown call to each handler is made synchronously. However, shutdown handler objects have time-out values for each of the shutdown processing member functions. If the handler does not return within the specified time-out period, shutdown processing continues with the next handler. The system shutdown service makes a best effort to include handlers that have timed out in future shutdown processing based on when the handler actually completes the last request and the state of the shutdown process at that point. Handlers can receive additional time by calling TShutdownServerHandle::NeedMoreTime.
Calling Context:
Called by the system shutdown service. PrepareForShutdown is called in a thread in the client's address space created by the system shutdown service when the handler was registered. Clients are responsible for managing any resultant concurrency issues.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TShutdownHandler::CompleteShutdown
virtual void CompleteShutdown ()
Interface Category:
API.
Purpose:
Derived classes override to handle actual shutdown. Actual shutdown might involve releasing resources, deleting objects, and terminating threads and tasks. Once this member function is called, clients are no longer expected to provide services. This might mean the client tasks actually terminate, or that the service just goes into a quiescent state and waits for task termination. Some clients can even continue to process requests, as long as they are prepared to have their tasks terminated at any time after they return from CompleteShutdown.
The CompleteShutdown call to each handler is made synchronously. However, shutdown handler objects have time-out values for each of the shutdown processing member functions. If the handler does not return within the specified time-out period, shutdown processing continues with the next handler. Handlers can receive additional time by calling TShutdownServerHandle::NeedMoreTime.
Calling Context:
Called by the system shutdown service. This is the final call made to the handler by the shutdown service. CompleteShutdown is called in a thread in the client's address space created by the system shutdown service when the handler was registered. Clients are responsible for managing any resultant concurrency issues.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TShutdownHandler::ShutdownCanceled
virtual void ShutdownCanceled ()
Interface Category:
API.
Purpose:
Derived classes can override this member function to handle the cancellation of a pending shutdown. The default behavior does nothing. This member function is called for all TShutdownHandler objects that have had their VerifyShutdown member functions called prior to the cancellation, so that they can resume normal processing.
Calling Context:
Called by system shutdown if the VerifyShutdown member function for this handler has been called and shutdown is subsequently canceled. ShutdownCanceled is called in a thread in the client's address space created by the system shutdown service when the handler was registered. Clients are responsible for managing any resultant concurrency issues.
Parameters:
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.
Copyright©1995 Taligent,Inc. All rights reserved.