Package com.google.appengine.api

Class ThreadManager

java.lang.Object

com.google.appengine.api.ThreadManager

public final class ThreadManager
extends Object

ThreadManager exposes a ThreadFactory that allows App Engine applications to spawn new threads. Refer to this discussion of threads for drawbacks of thread usage and possible alternatives.

Constructor Summary

Constructors

Constructor	Description
ThreadManager()

Method Summary

Modifier and Type	Method	Description
static ThreadFactory	backgroundThreadFactory()	Returns a ThreadFactory that will create threads that are independent of the current request.
static Thread	createBackgroundThread(Runnable runnable)	Create a new Thread that executes runnable independent of the current request.
static Thread	createThreadForCurrentRequest(Runnable runnable)	Create a new Thread that executes runnable for the duration of the current request.
static ThreadFactory	currentRequestThreadFactory()	Returns a ThreadFactory which will create threads scoped to the current request.
static Optional<ThreadFactory>	currentRequestThreadFactoryOptional()	Returns an Optional ThreadFactory which will create threads scoped to the current request.

Methods inherited from class java.lang.Object

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

Constructor Details

ThreadManager

public ThreadManager()

Method Details

currentRequestThreadFactory

public static ThreadFactory currentRequestThreadFactory()

Returns a ThreadFactory which will create threads scoped to the current request. These threads will be interrupted at the end of the current request and must complete within the request deadline. If they fail to, the instance containing them may be terminated.

The principal reason to use this method is so that the created threads can make App Engine API calls (com.google.appengine.api.*). In general, threads not associated with a request cannot make these API calls.

The returned factory is typically used with a call like Executors.newCachedThreadPool(ThreadFactory). Do not use the ExecutorService returned by this call after the request that created it has completed.

Note that calling ThreadFactory.newThread(java.lang.Runnable) on the returned instance may throw any of the unchecked exceptions mentioned by createBackgroundThread(java.lang.Runnable).

Throws:

NullPointerException - if the calling thread is not associated with a request.

currentRequestThreadFactoryOptional

public static Optional<ThreadFactory> currentRequestThreadFactoryOptional()

Returns an Optional ThreadFactory which will create threads scoped to the current request. These threads will be interrupted at the end of the current request and must complete within the request deadline. If they fail to, the instance containing them may be terminated.

If this method is not called from an App Engine request thread, returns an empty Optional instance.

The principal reason to use this method is so that the created threads can make App Engine API calls (com.google.appengine.api.*). In general, threads not associated with a request cannot make these API calls.

The returned factory is typically used with a call like Executors.newCachedThreadPool(ThreadFactory). Do not use the ExecutorService returned by this call after the request that created it has completed.

Note that calling ThreadFactory.newThread(java.lang.Runnable) on the returned instance may throw any of the unchecked exceptions mentioned by createBackgroundThread(java.lang.Runnable).

createThreadForCurrentRequest

public static Thread createThreadForCurrentRequest(Runnable runnable)

Create a new Thread that executes runnable for the duration of the current request. Calling this method is equivalent to invoking ThreadFactory.newThread(java.lang.Runnable) on the ThreadFactory returned from currentRequestThreadFactory(). This thread will be interrupted at the end of the current request and must complete within the request deadline. If it fails to, the instance containing it may be terminated.

Throws:

IllegalStateException - if you try to create more than 50 threads in a single request.

NullPointerException - if the calling thread is not associated with a request.

ApiProxy.FeatureNotEnabledException - If this application cannot use this feature.

backgroundThreadFactory

public static ThreadFactory backgroundThreadFactory()

Returns a ThreadFactory that will create threads that are independent of the current request.

This ThreadFactory can currently only be used by backends.

Note that calling ThreadFactory.newThread(java.lang.Runnable) on the returned instance may throw any of the unchecked exceptions mentioned by createBackgroundThread(java.lang.Runnable).

createBackgroundThread

public static Thread createBackgroundThread(Runnable runnable)

Create a new Thread that executes runnable independent of the current request. Calling this method is equivalent to invoking ThreadFactory.newThread(java.lang.Runnable) on the ThreadFactory returned from backgroundThreadFactory().

This method can currently only be used by backends.

Throws:

ApiProxy.FeatureNotEnabledException - If this application cannot use this feature.

ApiProxy.CancelledException - If the request was interrupted while creating the new thread.

ApiProxy.ApiDeadlineExceededException - If creation of the new thread took too long.