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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	ShutdownNotifier.ShutdownRequestListener

Method Summary

Modifier and Type	Method	Description
static ShutdownNotifier	createDummy()	Create an instance that will never return true for shouldShutdown() and will never notify its listeners.
String	getReason()	Return the reason for the shutdown request on this instance.
static ShutdownNotifier.ShutdownRequestListener	interruptCurrentThreadOnShutdown()	Utility method for creating a ShutdownNotifier.ShutdownRequestListener that interrupts the current thread (that calls this method) on a shutdown.
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).
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.
boolean	shouldShutdown()	Check whether a shutdown was previously requested.
void	shutdownIfNecessary()	Check whether a shutdown was previously requested, and throw an InterruptedException in this case.
void	unregister(ShutdownNotifier.ShutdownRequestListener listener)	Unregister a listener.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

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 immediately after this instance was constructed, and may return true later on. After it returned true once it 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. Once a shutdown was requested, 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.