edu.emory.mathcs.util.concurrent
Class ExecutorUtils

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

public class ExecutorUtils
extends java.lang.Object

Version:
1.0
Author:
Dawid Kurzyniec

Nested Class Summary
static class ExecutorUtils.SafeThreadFactory
          Thread factory implementation that attempts to ensure that created threads are equivalent regardless of threads that request creation.
 
Method Summary
static Future completedFuture(java.lang.Object result)
          Creates a successfully completed future with specified result.
static Future completedFuture(java.lang.Object result, Callback cb)
          Creates a successfully completed future with specified result and completion callback.
static Callable delegatedCallable(Callable callable)
          Returns a callable wrapper that ensures that executions (even if performed by different threads) inherit current access control context and ThreadContext.
static Callable delegatedCallable(Callable callable, ThreadContext tc)
          Returns a callable wrapper that ensures that executions (even if performed by different threads) inherit current access control context and the specified ThreadContext.
static java.lang.Runnable delegatedRunnable(java.lang.Runnable runnable)
          Returns a runnable wrapper that ensures that executions (even if performed by different threads) inherit current access control context and ThreadContext.
static java.lang.Runnable delegatedRunnable(java.lang.Runnable runnable, ThreadContext tc)
          Returns a runnable wrapper that ensures that executions (even if performed by different threads) inherit current access control context and the specified ThreadContext.
static Future failedFuture(java.lang.Throwable cause)
          Creates a failed future with specified failure cause.
static Future failedFuture(java.lang.Throwable cause, Callback cb)
          Creates a failed future with specified failure cause and completion callback.
static ExecutorService newFixedSecureThreadPool(int nThreads)
          Creates a thread pool that reuses a fixed set of threads operating off a shared unbounded queue.
static ExecutorService newSecureCachedThreadPool()
          Creates a thread pool that creates new threads as needed, but will reuse previously constructed threads when they are available.
static ExecutorService newSecureSingleThreadExecutor()
          Creates an Executor that uses a single worker thread operating off an unbounded queue.
static ThreadFactory safeThreadFactory()
          Returns a thread factory implementation that attempts to ensure that created threads are equivalent regardless of threads that request creation.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

newFixedSecureThreadPool

public static ExecutorService newFixedSecureThreadPool(int nThreads)
Creates a thread pool that reuses a fixed set of threads operating off a shared unbounded queue. If any thread terminates due to a failure during execution prior to shutdown, a new one will take its place if needed to execute subsequent tasks.

Parameters:
nThreads - the number of threads in the pool
Returns:
the newly created thread pool

newSecureSingleThreadExecutor

public static ExecutorService newSecureSingleThreadExecutor()
Creates an Executor that uses a single worker thread operating off an unbounded queue. (Note however that if this single thread terminates due to a failure during execution prior to shutdown, a new one will take its place if needed to execute subsequent tasks.) Tasks are guaranteed to execute sequentially, and no more than one task will be active at any given time. Unlike the otherwise equivalent newFixedThreadPool(1) the returned executor is guaranteed not to be reconfigurable to use additional threads.

Returns:
the newly created single-threaded Executor

newSecureCachedThreadPool

public static ExecutorService newSecureCachedThreadPool()
Creates a thread pool that creates new threads as needed, but will reuse previously constructed threads when they are available. These pools will typically improve the performance of programs that execute many short-lived asynchronous tasks. Calls to execute will reuse previously constructed threads if available. If no existing thread is available, a new thread will be created and added to the pool. Threads that have not been used for sixty seconds are terminated and removed from the cache. Thus, a pool that remains idle for long enough will not consume any resources. Note that pools with similar properties but different details (for example, timeout parameters) may be created using ThreadPoolExecutor constructors.

Returns:
the newly created thread pool

delegatedRunnable

public static java.lang.Runnable delegatedRunnable(java.lang.Runnable runnable)
Returns a runnable wrapper that ensures that executions (even if performed by different threads) inherit current access control context and ThreadContext. In particular, the runnable will always run with the same access permissions, delegatable thread locals, and context class loader, determined at the time of invocation of this method.


delegatedRunnable

public static java.lang.Runnable delegatedRunnable(java.lang.Runnable runnable,
                                                   ThreadContext tc)
Returns a runnable wrapper that ensures that executions (even if performed by different threads) inherit current access control context and the specified ThreadContext. In particular, the runnable will always run with the same access permissions, delegatable thread locals, and context class loader, determined at the time of invocation of this method.


delegatedCallable

public static Callable delegatedCallable(Callable callable)
Returns a callable wrapper that ensures that executions (even if performed by different threads) inherit current access control context and ThreadContext. In particular, the callable will always run with the same access permissions, delegatable thread locals, and context class loader, determined at the time of invocation of this method.


delegatedCallable

public static Callable delegatedCallable(Callable callable,
                                         ThreadContext tc)
Returns a callable wrapper that ensures that executions (even if performed by different threads) inherit current access control context and the specified ThreadContext. In particular, the callable will always run with the same access permissions, delegatable thread locals, and context class loader, determined at the time of invocation of this method.


safeThreadFactory

public static ThreadFactory safeThreadFactory()
Returns a thread factory implementation that attempts to ensure that created threads are equivalent regardless of threads that request creation. Precisely, created threads belong to the same thread group, and they inherit a "parent thread context" (access control context, DelegatableThreadLocals, etc.) from the invoker of this method rather than from the invoker of ExecutorUtils.SafeThreadFactory.newThread(java.lang.Runnable).

Use with ThreadPoolExecutor, to ensure deterministic behavior and consistent security properties. Nevertheless, stronger semantics are often neccessary in security-sensitive applications. In particular, it may be required that worker tasks run within access control context and with delegatable locals of the thread that scheduled the task, which may generally be distinct from both the thread pool creator and the worker thread creator. If such security semantics is needed, use SecureThreadPoolExecutor or one of "newSecure*" methods.


completedFuture

public static Future completedFuture(java.lang.Object result)
Creates a successfully completed future with specified result.

Parameters:
result - the result of the future
Returns:
the completed future

completedFuture

public static Future completedFuture(java.lang.Object result,
                                     Callback cb)
Creates a successfully completed future with specified result and completion callback. If not null, the callback is immediately notified about the completion.

Parameters:
result - the result of the future
cb - the callback to be notified about successful completion
Returns:
the completed future

failedFuture

public static Future failedFuture(java.lang.Throwable cause)
Creates a failed future with specified failure cause.

Parameters:
cause - the cause of failure
Returns:
the completed future

failedFuture

public static Future failedFuture(java.lang.Throwable cause,
                                  Callback cb)
Creates a failed future with specified failure cause and completion callback. If not null, the callback is immediately notified about the completion.

Parameters:
cause - the cause of failure
cb - the callback to be notified about failure
Returns:
the completed future