edu.emory.mathcs.util.concurrent
Class ThreadContext

java.lang.Object
  extended byedu.emory.mathcs.util.concurrent.ThreadContext

public class ThreadContext
extends java.lang.Object

Represents an immutable snapshot of a thread state. The state consists of delegatable thread locals, context class loader, and a priority. After the snapshot has been taken, it is later possible to execute tasks within that previously stored context using one of perform methods. The thread executing the task need not be the same as the one for which the snapshot was originally taken; that is, the state can be recovered (for the duration of the task) in any thread invoking "perform".

This class is particularly useful in developing thread pools and asynchronous invocation frameworks, where it is common that tasks are executed in generic asynchronous threads on behalf of invokers initiating them from other threads. This class allows such worker threads to temporarily inherit initiator thread's properties, such as delegatable thread locals or a context class loader.

The snapshot represented by this class is immutable; that is, it is not altered during the execution of "perform" methods. However, if desired, it is possible to implement state persistence via chained propagation: that is, a replacement snapshot should be re-taken by the task at the end of the execution.

Note that non-delegatable thread locals (e.g. normal ThreadLocals and InheritableThreadLocals) cannot be detached from their threads and thus are not propagated through the thread context. For instance, non-delegatable thread locals set during a "perform" call will remain set in the current thread after the call completes.


Method Summary
static ThreadContext create(java.lang.ClassLoader ccl)
           
static ThreadContext create(java.lang.ClassLoader ccl, int priority)
           
 boolean equals(java.lang.Object other)
           
static ThreadContext getContext()
          Takes the snapshot of the current thread's state.
 int hashCode()
           
 java.lang.Object perform(Callable call)
          Temporarily recovers current thread's state from this snapshot and then executes the specified call.
 java.lang.Object perform(java.security.PrivilegedAction action)
          Temporarily recovers current thread's state from this snapshot and then performs the specified action.
 java.lang.Object perform(java.security.PrivilegedExceptionAction action)
          Temporarily recovers current thread's state from this snapshot and then performs the specified action.
 void perform(java.lang.Runnable task)
          Temporarily recovers current thread's state from this snapshot and then executes the specified task.
 java.security.PrivilegedAction wrap(java.security.PrivilegedAction action)
           
 java.security.PrivilegedExceptionAction wrap(java.security.PrivilegedExceptionAction action)
           
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getContext

public static ThreadContext getContext()
Takes the snapshot of the current thread's state. The state consists of context class loader, delegatable thread locals, and a priority. The snapshot is immutable.


create

public static ThreadContext create(java.lang.ClassLoader ccl,
                                   int priority)

create

public static ThreadContext create(java.lang.ClassLoader ccl)

perform

public void perform(java.lang.Runnable task)
Temporarily recovers current thread's state from this snapshot and then executes the specified task. In result, the task will observe access control context, delegatable thread locals, and the context class loader, as they existed when the snapshot was taken (perhaps in a different thread). Upon completion, the original thread state is restored.

Parameters:
task - the task to execute

perform

public java.lang.Object perform(Callable call)
                         throws java.lang.Exception
Temporarily recovers current thread's state from this snapshot and then executes the specified call. In result, the call will observe access control context, delegatable thread locals, and the context class loader, as they existed when the snapshot was taken (perhaps in a different thread). Upon completion, the original thread state is restored.

Parameters:
call - the call to execute
Returns:
the result of the call
Throws:
java.lang.Exception - thrown from the call

perform

public java.lang.Object perform(java.security.PrivilegedAction action)
Temporarily recovers current thread's state from this snapshot and then performs the specified action. In result, the action will observe access control context, delegatable thread locals, and the context class loader, as they existed when the snapshot was taken (perhaps in a different thread). Upon completion, the original thread state is restored.

Parameters:
action - the action to perform
Returns:
the result of the action

perform

public java.lang.Object perform(java.security.PrivilegedExceptionAction action)
                         throws java.security.PrivilegedActionException
Temporarily recovers current thread's state from this snapshot and then performs the specified action. In result, the action will observe access control context, delegatable thread locals, and the context class loader, as they existed when the snapshot was taken (perhaps in a different thread). Upon completion, the original thread state is restored.

Parameters:
action - the action to perform
Returns:
the result of the action
Throws:
java.security.PrivilegedActionException - if action threw an exception

wrap

public java.security.PrivilegedAction wrap(java.security.PrivilegedAction action)

wrap

public java.security.PrivilegedExceptionAction wrap(java.security.PrivilegedExceptionAction action)

hashCode

public int hashCode()

equals

public boolean equals(java.lang.Object other)