1 // Copyright 2011 Google Inc. All Rights Reserved.
3 package com
.google
.appengine
.api
;
5 import com
.google
.apphosting
.api
.ApiProxy
;
6 import java
.util
.concurrent
.ThreadFactory
;
9 * {@code ThreadManager} exposes a {@link ThreadFactory} that allows
10 * App Engine applications to spawn new threads.
13 public final class ThreadManager
{
14 private static final String REQUEST_THREAD_FACTORY_ATTR
=
15 "com.google.appengine.api.ThreadManager.REQUEST_THREAD_FACTORY";
17 private static final String BACKGROUND_THREAD_FACTORY_ATTR
=
18 "com.google.appengine.api.ThreadManager.BACKGROUND_THREAD_FACTORY";
21 * Returns a {@link ThreadFactory} that will create threads scoped
22 * to the current request. These threads will be interrupted at the
23 * end of the current request and must complete within the request
26 * <p>Your code has limited access to the threads created by this
27 * {@link ThreadFactory}. For example, you can call
28 * {@link Thread#setUncaughtExceptionHandler} and
29 * {@link Thread#interrupt}, but not {@link Thread#stop} or any
30 * other methods that require
31 * {@code RuntimePermission("modifyThread")}.
33 * <p>The Java runtime will throw java.lang.IllegalStateException
34 * if you try to create more than 50 threads in a single request.
36 * <p>Note that calling {@link ThreadFactory#newThread} on the
37 * returned instance may throw any of the unchecked exceptions
38 * mentioned by {@link #createBackgroundThread}.
40 public static ThreadFactory
currentRequestThreadFactory() {
41 return (ThreadFactory
) ApiProxy
.getCurrentEnvironment().getAttributes().get(
42 REQUEST_THREAD_FACTORY_ATTR
);
46 * Create a new {@link Thread} that executes {@code runnable} for
47 * the duration of the current request. Calling this method is
48 * equivalent to invoking {@link ThreadFactory#newThread} on the
49 * ThreadFactory returned from {@link #currentRequestThreadFactory}.
50 * This thread will be interrupted at the end of the current request
51 * and must complete within the request deadline.
53 * @throws IllegalStateException if you try to create more than 50 threads in a single request.
54 * @throws ApiProxy.FeatureNotAvailableException If this application
55 * cannot use this feature.
57 public static Thread
createThreadForCurrentRequest(Runnable runnable
) {
58 return currentRequestThreadFactory().newThread(runnable
);
62 * Returns a {@link ThreadFactory} that will create threads that are
63 * independent of the current request.
65 * <p>This ThreadFactory can currently only be used by backends.
67 * <p>Note that calling {@link ThreadFactory#newThread} on the
68 * returned instance may throw any of the unchecked exceptions
69 * mentioned by {@link #createBackgroundThread}.
71 public static ThreadFactory
backgroundThreadFactory() {
72 return (ThreadFactory
) ApiProxy
.getCurrentEnvironment().getAttributes().get(
73 BACKGROUND_THREAD_FACTORY_ATTR
);
77 * Create a new {@link Thread} that executes {@code runnable}
78 * independent of the current request. Calling this method is
79 * equivalent to invoking {@link ThreadFactory#run} on the
80 * ThreadFactory returned from {@link #backgroundThreadFactory}.
82 * <p>This method can currently only be used by backends.
84 * @throws ApiProxy.FeatureNotAvailableException If this application
85 * cannot use this feature.
86 * @throws ApiProxy.CancelledException If the request was interrupted
87 * while creating the new thread.
88 * @throws ApiProxy.ApiDeadlineExceededException If creation of the
89 * new thread took too long.
91 public static Thread
createBackgroundThread(Runnable runnable
) {
92 return backgroundThreadFactory().newThread(runnable
);