Package org.sosy_lab.common

Class ShutdownManager

java.lang.Object
org.sosy_lab.common.ShutdownManager
public final class ShutdownManager extends Object
Together with ShutdownNotifier, this class implements a service for distributing shutdown requests throughout an application's component, potentially in a hierarchy.

Possible use cases are for example to implement timeouts or respond to Ctrl+C by terminating the application in a graceful manner, i.e., letting the running code terminate itself and do cleanup. It works passively, i.e., the running code is not forcibly interrupted, but needs to check the ShutdownNotifier instance that is associated with this instance regularly. This ensures that the running code is not left in an unclean state.

A ShutdownManager can only be used for one shutdown request: After creation it starts in the fresh "no shutdown requested" state. After the first call to requestShutdown(String) is in the "shutdown requested" state and remains there forever. All subsequent calls to getNotifier().shouldShutdown() will return true, and further calls to requestShutdown(String) are ignored.

This class is the entry point and allows issuing shutdown requests with requestShutdown(String). All components that need to get these requests or check whether the should terminate should get the ShutdownNotifier instance that is returned by getNotifier(). By handing out only ShutdownNotifier instances instead of ShutdownManager instances, it can be controlled which components have the possibility to issue shutdown requests, and which components may only respond to them.

This class supports a hierarchy of instances. Setting the shutdown request on a higher-level instance will do the same in all children instances (recursively), but not vice-versa. This can be used for example to implement global and component-specific timeouts at the same time, with the former overriding the latter if necessary.

This class does not implement any timeout by itself. A separate component needs to be used that implements the timeout and calls {requestShutdown(String)} in case it is reached.

This class and ShutdownNotifier are completely thread safe.

  • Method Details

    • create

      public static ShutdownManager create()
      Create a fresh new instance of this class. The associated ShutdownNotifier has no listeners and shutdown has not been requested yet.

    • createWithParent

      public static ShutdownManager createWithParent(ShutdownNotifier parent)
      Create a fresh new instance of this class in a hierarchy.

      The new instance is considered to be a child of the given ShutdownNotifier, this means as soon as the parent has a shutdown requested, the same is true for the child instance (but not vice-versa). Note that if the parent instance already has shutdown requested, the new instance is also immediately in the same state.

      Parameters:
      parent - A non-null ShutdownNotifier instance.

    • getNotifier

      public ShutdownNotifier getNotifier()

    • requestShutdown

      public void requestShutdown(String pReason)
      Request a shutdown of all components that check the associated ShutdownNotifier, by letting ShutdownNotifier.shouldShutdown() return true in the future, and by notifying all registered listeners. Only the first call to this method has an effect. When this method returns, it is guaranteed that all currently registered listeners where notified and have been unregistered.
      Parameters:
      pReason - A non-null human-readable string that tells the user why a shutdown was requested.