com.bigdata.util.concurrent

Class Haltable<V>

java.lang.Object

com.bigdata.util.concurrent.Haltable<V>

All Implemented Interfaces:

IHaltable<V>, Future<V>

public class Haltable<V>
extends Object
implements IHaltable<V>

Abstract base class for tasks whose processing may be halted asynchronously. While this bears some resemblance to Future, this class is used in contexts where the process to be halted does not map nicely into a Callable or Runnable and hence can not be modeled using a FutureTask.

This class embeds certain knowledge about which exceptions may be observed during normal termination of asynchronous processes using I/O, thread pools, and IBlockingBuffers. See isNormalTerminationCause(Throwable) for a list of the Throwable causes which are treated as normal termination.

Version:

$Id: AbstractHaltableProcess.java 2265 2009-10-26 12:51:06Z thompsonbry $

Author:

Bryan Thompson

Constructor Summary

Constructors

Constructor and Description
Haltable() Designated constructor.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	cancel(boolean mayInterruptIfRunning)
V	get()
V	get(long timeout, TimeUnit unit)
Throwable	getAsThrownCause() Return the first cause regardless of whether it is indicative of normal termination and null iff no cause has been set.
Throwable	getCause() Return the first Throwable which caused this process to halt, but only for abnormal termination.
<T extends Throwable> T	halt(T cause) Halt (exception thrown).
void	halt(V v) Halt (normal termination).
void	halted() Return unless processing has been halted.
boolean	isCancelled()
protected boolean	isDeadlineTerminationCause(Throwable cause) Note: There is a special exemption for QueryTimeoutException.
boolean	isDone() Return true if the process is done.
boolean	isError() Return true if the process was halted by a Throwable not included in the set of known normal termination causes.
protected boolean	isNormalTerminationCause(Throwable cause) Return true if the Throwable is a known normal termination cause for the process.
static boolean	isTerminationByInterrupt(Throwable cause)

Methods inherited from class java.lang.Object

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

Constructor Detail

Haltable

public Haltable()

Designated constructor.

Method Detail

halt

public final void halt(V v)

Halt (normal termination).

Specified by:

halt in interface IHaltable<V>

halt

public final <T extends Throwable> T halt(T cause)

Halt (exception thrown). The caller is responsible for throwing the cause out of their own context.

Specified by:

halt in interface IHaltable<V>

Parameters:

cause - The cause (required).

Returns:

The argument.

halted

public final void halted()

Return unless processing has been halted. The method should be invoked from within the execution of the process itself so that it may notice asynchronous termination. It will throw out the wrapped first cause if the process is halted.

Note: External processes waiting on the Future interface should use isDone() which does not have the semantics of asserting that the process should still be running.

Throws:

RuntimeException - wrapping the firstCause iff processing has been halted.

cancel

public final boolean cancel(boolean mayInterruptIfRunning)

Specified by:

cancel in interface Future<V>

get

public final V get()
            throws InterruptedException,
                   ExecutionException

Specified by:

get in interface Future<V>

Throws:

InterruptedException

ExecutionException

get

public final V get(long timeout,
    TimeUnit unit)
            throws InterruptedException,
                   ExecutionException,
                   TimeoutException

Specified by:

get in interface Future<V>

Throws:

InterruptedException

ExecutionException

TimeoutException

isDone

public final boolean isDone()

Return true if the process is done.

Specified by:

isDone in interface Future<V>

isError

public final boolean isError()

Return true if the process was halted by a Throwable not included in the set of known normal termination causes.

isCancelled

public boolean isCancelled()

Specified by:

isCancelled in interface Future<V>

getCause

public final Throwable getCause()

Description copied from interface: IHaltable

Return the first Throwable which caused this process to halt, but only for abnormal termination.

IHaltable considers exceptions triggered by an interrupt to be normal termination of the process and will return null for such exceptions.

Specified by:

getCause in interface IHaltable<V>

Returns:

The first Throwable which caused this process to halt and null if the process has not halted or if it halted through normal termination.

getAsThrownCause

public final Throwable getAsThrownCause()

Description copied from interface: IHaltable

Return the first cause regardless of whether it is indicative of normal termination and null iff no cause has been set.

Specified by:

getAsThrownCause in interface IHaltable<V>

isNormalTerminationCause

protected boolean isNormalTerminationCause(Throwable cause)

Return true if the Throwable is a known normal termination cause for the process. The method inspects the stack trace, examining both the outer and InnerCauses. The following causes are interpreted as normal termination:

InterruptedException

The process was terminated by an interrupt. Interrupts are typically used to terminate asynchronous processes when their production limit has been satisfied or the consumer otherwise chooses to IAsynchronousIterator.close() the iterator through which they are consuming results from the process.

CancellationException

A process has been canceled using its Future.

ClosedByInterruptException

A process was interrupted during an IO operation.

BufferClosedException

The IBlockingBuffer on which the process was writing was asynchronously closed.

RejectedExecutionException

A process was not executed because the pool against which it was submitted had been shutdown (this of course implies that the work queue was unbounded as a bounded pool will throw this exception if the work queue is full).

Parameters:

cause - The Throwable.

Returns:

true if the Throwable indicates normal termination.

See Also:

getCause()

isDeadlineTerminationCause

protected boolean isDeadlineTerminationCause(Throwable cause)

Note: There is a special exemption for QueryTimeoutException. This can not be interpreted as "normal" termination since we want the exception to be thrown out and then turned into the corresponding openrdf exception. However, we do not want to log a full stack trace for this since it is, in fact, an exception termination mode for a query.

See Also:

Query timeout only checked at operator start/stop.

isTerminationByInterrupt

public static boolean isTerminationByInterrupt(Throwable cause)