java/src/main/com/google/appengine/api/ThreadManager.java

   1 // Copyright 2011 Google Inc. All Rights Reserved.
   2
   3 package com.google.appengine.api;
   4
   5 import com.google.apphosting.api.ApiProxy;
   6 import java.util.concurrent.ThreadFactory;
   7
   8 /**
   9  * {@code ThreadManager} exposes a {@link ThreadFactory} that allows
  10  * App Engine applications to spawn new threads.
  11  *
  12  */
  13 public final class ThreadManager {
  14   private static final String REQUEST_THREAD_FACTORY_ATTR =
  15       "com.google.appengine.api.ThreadManager.REQUEST_THREAD_FACTORY";
  16
  17   private static final String BACKGROUND_THREAD_FACTORY_ATTR =
  18       "com.google.appengine.api.ThreadManager.BACKGROUND_THREAD_FACTORY";
  19
  20   /**
  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
  24    * deadline.
  25    *
  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")}.
  32    *
  33    * <p>The Java runtime will throw java.lang.IllegalStateException
  34    * if you try to create more than 50 threads in a single request.
  35    *
  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}.
  39    */
  40   public static ThreadFactory currentRequestThreadFactory() {
  41     return (ThreadFactory) ApiProxy.getCurrentEnvironment().getAttributes().get(
  42         REQUEST_THREAD_FACTORY_ATTR);
  43   }
  44
  45   /**
  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.
  52    *
  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.
  56    */
  57   public static Thread createThreadForCurrentRequest(Runnable runnable) {
  58     return currentRequestThreadFactory().newThread(runnable);
  59   }
  60
  61   /**
  62    * Returns a {@link ThreadFactory} that will create threads that are
  63    * independent of the current request.
  64    *
  65    * <p>This ThreadFactory can currently only be used by backends.
  66    *
  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}.
  70    */
  71   public static ThreadFactory backgroundThreadFactory() {
  72     return (ThreadFactory) ApiProxy.getCurrentEnvironment().getAttributes().get(
  73         BACKGROUND_THREAD_FACTORY_ATTR);
  74   }
  75
  76   /**
  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}.
  81    *
  82    * <p>This method can currently only be used by backends.
  83    *
  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.
  90    */
  91   public static Thread createBackgroundThread(Runnable runnable) {
  92     return backgroundThreadFactory().newThread(runnable);
  93   }
  94 }