It is also subclassable, so that a subclass of {@link NonLocalExit} can override
* the factory method {@link NonLocalExit#makeJump() makeJump}.
* This might allow an ingenious client to sharpen the type of the catch clause
* at the end of the {@link NonLocalExit NonLocalExit’s} scope.
*/
public static
class Jump
// Might want to be a simple Throwable (or Error), since there is
// a tendency for user code to catch RuntimeExceptions indiscriminately.
extends RuntimeException
implements Cloneable
{
// no public members:
protected Jump() { }
protected Jump clone() { // the usual clone pattern...
try { return (Jump) super.clone(); }
catch (CloneNotSupportedException ex) { throw new InternalError(); }
}
// nested in here to get lazy creation of the first Jump:
static final Jump INSTANCE = TRACE ? null : new Jump();
}
/** This is called by {@link #jump()} to create the throwable which my scope will catch.
* An ingenious client might override this so as to use a sharper exception type
* when there are overlapping and independent non-local returns in a program.
* This is not the common case, though. The ingenious client should consider
* using {@link Jump#clone() clone} of a pre-allocated subclass instance, in order
* to avoid the high cost of {@link Throwable#fillInStackTrace() Throwable.fillInStackTrace}.
*/
protected Jump makeJump() {
return
TRACE ? new Jump() : // call fillInStackTrace !
Jump.INSTANCE.clone();
}
/** Accessibility is limited to the current thread,
* and (when I go out of scope) is set to null to indicate no access.
*/
// This variable is only used if checking is enabled,
protected Thread scope;
/** The most recent exception created to throw at me is stored here.
* It is used to distinguish that jump from other jumps to similar scopes.
* It starts out a null. I can be jumped to any number of times,
* but only one jump will succeed.
*/
protected Jump jump;
private void initState() {
this.scope = Thread.currentThread();
}
private void checkState() {
Thread scope = this.scope;
if (scope != Thread.currentThread()) {
lose(scope, this.jump);
}
}
// Bulky and rarely-used method to produce a helpful error message.
// Do not inline into checkState.
private static void lose(Thread scope, Jump jump) {
if (scope != null)
throw new IllegalStateException("cannot jump to another thread "+scope);
if (jump != null)
throw new IllegalStateException("cannot jump twice to the same target ", jump);
throw new IllegalStateException("illegal jump state");
}
// Public API: create, maybe jump, catch-and-match, finally close.
// See callWithNonLocalExit for below.
/** Create a non-local exit point at the start of some scope.
* Caller is responsible to catch, within the scope, {@link Jump Jumps} which may be directed
* at this point, and to {@link #close() close the exit point} when it goes out of scope.
*
Example code: *
* NonLocalExit exit = new NonLocalExit();
* try {
* callSomethingRecursiveWithAnEscapeHatch(exit);
* return somethingLocal;
* } catch (NonLocalExit.Jump t) {
* if (!exit.matches(t))
* // These are not the droids you're looking for. Move along.
* throw t;
* return somethingElseLocal;
* } finally {
* exit.close();
* }
*
* Note that this class can be subclassed to “box” a return value,
* which would be delivered instead of somethingElseLocal
* in the above example.
*/
public NonLocalExit() {
// Mark this exit point as accessible (in this thread).
if (!NOCHECK) initState();
// else null scope means "Do I feel lucky today?"
}
/** Make a non-local jump to the end of my scope.
* Concretely, throw an exception to my associated
* exception handler which matches me.
* This is usually invoked at most once per exit point instance.
*/
public void jump() {
// Make sure we are active in the correct thread.
if (!NOCHECK) checkState();
// Use an internal throwable to transfer the control.
Jump t = makeJump();
jump = t; // mark target as 'in-flight' with t
throw t; // happy landings!
}
// Ugly multiple jump scenario, in pseudocode:
// L: { try { L.jump(); } finally { L.jump(); } }
// It's ugly, but it will work.
/** Must be used in my associated catch clause to verify that
* a passing exception is one this pertains to me.
* If it returns true, then the caller should pass control
* normally out of my associated scope.
* If it returns false, the the caller must
* rethrow the caught exception, because it is aimed at a different
* scope (i.e., a different {@link NonLocalExit} instance).
*/
public boolean matches(Throwable t) {
return (jump == t);
}
/** Make me go out of scope. Caller should do this in a
* finally clause, or else error checking
* may produce unhelpful results.
*/
public void close() {
// Mark this exit point as dead (inaccessible even in this thread).
if (!NOCHECK)
this.scope = null;
}
}
//////////////////////////////
// The rest of this file is really example code and can be removed.
// Typical run:
// % javac NonLocalExit.java && java NonLocalExitExample
// Warming up...
// Making timing run:
// Time per iteration: 1.891 us
class NonLocalExitExample {
// Canonical usage:
interface Callable