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>Note that calling {@link ThreadFactory#newThread} on the
  34    * returned instance may throw any of the unchecked exceptions
  35    * mentioned by {@link #createBackgroundThread}.
  36    */
  37   public static ThreadFactory currentRequestThreadFactory() {
  38     return (ThreadFactory) ApiProxy.getCurrentEnvironment().getAttributes().get(
  39         REQUEST_THREAD_FACTORY_ATTR);
  40   }
  41
  42   /**
  43    * Create a new {@link Thread} that executes {@code runnable} for
  44    * the duration of the current request.  Calling this method is
  45    * equivalent to invoking {@link ThreadFactory#run} on the
  46    * ThreadFactory returned from {@link #currentRequestThreadFactory}.
  47    * This thread will be interrupted at the end of the current request
  48    * and must complete within the request deadline.
  49    *
  50    * @throws ApiProxy.FeatureNotAvailableException If this application
  51    * cannot use this feature.
  52    */
  53   public static Thread createThreadForCurrentRequest(Runnable runnable) {
  54     return currentRequestThreadFactory().newThread(runnable);
  55   }
  56
  57   /**
  58    * Returns a {@link ThreadFactory} that will create threads that are
  59    * independent of the current request.
  60    *
  61    * <p>This ThreadFactory can currently only be used by backends.
  62    *
  63    * <p>Note that calling {@link ThreadFactory#newThread} on the
  64    * returned instance may throw any of the unchecked exceptions
  65    * mentioned by {@link #createBackgroundThread}.
  66    */
  67   public static ThreadFactory backgroundThreadFactory() {
  68     return (ThreadFactory) ApiProxy.getCurrentEnvironment().getAttributes().get(
  69         BACKGROUND_THREAD_FACTORY_ATTR);
  70   }
  71
  72   /**
  73    * Create a new {@link Thread} that executes {@code runnable}
  74    * independent of the current request.  Calling this method is
  75    * equivalent to invoking {@link ThreadFactory#run} on the
  76    * ThreadFactory returned from {@link #backgroundThreadFactory}.
  77    *
  78    * <p>This method can currently only be used by backends.
  79    *
  80    * @throws ApiProxy.FeatureNotAvailableException If this application
  81    * cannot use this feature.
  82    * @throws ApiProxy.CancelledException If the request was interrupted
  83    * while creating the new thread.
  84    * @throws ApiProxy.ApiDeadlineExceededException If creation of the
  85    * new thread took too long.
  86    */
  87   public static Thread createBackgroundThread(Runnable runnable) {
  88     return backgroundThreadFactory().newThread(runnable);
  89   }
  90 }