Package org.sosy_lab.common

Class ShutdownNotifier

java.lang.Object
org.sosy_lab.common.ShutdownNotifier
public final class ShutdownNotifier extends Object
This class allows code to check whether it should terminate for some reason, and to be notified of such requests.

It works passively, the running analysis will not be interrupted directly, but instead it has to check every then and now whether it should shutdown. This ensures that the running code is not left in an unclean state.

The check whether a shutdown was requested is cheap and should be done quite often in order to ensure a timely response to a shutdown request. As a rule of thumb, all operations that may take longer than 1s should take care of calling shouldShutdown() or shutdownIfNecessary() from time to time.

Shutdown requests cannot be issued via this class, but only via ShutdownManager to allow restricting which code is allowed to request shutdowns.

Instances of this class cannot be created directly, instead create a ShutdownManager and call ShutdownManager.getNotifier().

This class is completely thread safe.

  • Method Details

    • createDummy

      public static ShutdownNotifier createDummy()
      Create an instance that will never return true for shouldShutdown() and will never notify its listeners. This may be handy for tests.

      To create a real usable ShutdownNotifier, use ShutdownManager.create().

    • shouldShutdown

      public boolean shouldShutdown()
      Check whether a shutdown was previously requested. This method returns false as long as no shutdown was requested from the ShutdownManager that handed out this ShutdownNotifier instance. After such a shutdown was requested, this method returns true and will always keep returning true, and never return false again. Calling this method is very cheap.

    • shutdownIfNecessary

      public void shutdownIfNecessary() throws InterruptedException
      Check whether a shutdown was previously requested, and throw an InterruptedException in this case. Otherwise, do nothing. Once a shutdown was requested from the ShutdownManager that handed out this ShutdownNotifier instance, every call to this method will throw an exception. In the common case that no shutdown was yet requested, calling this method is very cheap.
      Throws:
      InterruptedException - If a shutdown was requested.

    • getReason

      public String getReason()
      Return the reason for the shutdown request on this instance.
      Returns:
      A non-null human-readable string.
      Throws:
      IllegalStateException - If there was no shutdown request on this instance.

    • register

      public void register(ShutdownNotifier.ShutdownRequestListener listener)
      Register a listener that will be notified once a shutdown is requested for the first time on the associated ShutdownManager instance with ShutdownManager.requestShutdown(String).

      Listeners registered when shouldShutdown() already returns true will never be notified (so calling this method at that time has no effect).

      This class keeps only weak reference to the listener to allow the GC to collect them, so make sure to keep a strong reference to your instance as long as you won't to be notified.

      Parameters:
      listener - A non-null and not already registered listener.

    • registerAndCheckImmediately

      public void registerAndCheckImmediately(ShutdownNotifier.ShutdownRequestListener listener)
      Register a listener that will be notified once a shutdown is requested for the first time on the associated ShutdownManager instance with ShutdownManager.requestShutdown(String), or immediately if this was already the case.

      Use this method to avoid a race condition when registering the listener and checking for a requested shutdown at the same time (you could loose a notification).

      This class keeps only weak reference to the listener to allow the GC to collect them, so make sure to keep a strong reference to your instance as long as you won't to be notified.

      Parameters:
      listener - A non-null and not already registered listener.

    • unregister

      public void unregister(ShutdownNotifier.ShutdownRequestListener listener)
      Unregister a listener. This listener will not be notified in the future. It is safe to call this method twice with the same listener. It is not necessary to call this method for a listener that was already notified.
      Parameters:
      listener - A previously registered listener.

    • interruptCurrentThreadOnShutdown

      public static ShutdownNotifier.ShutdownRequestListener interruptCurrentThreadOnShutdown()
      Utility method for creating a ShutdownNotifier.ShutdownRequestListener that interrupts the current thread (that calls this method) on a shutdown. Note that this method does not actually do anything, you need to register the returned listener with an instance of this class.