1 files changed, 89 insertions, 1 deletions
diff --git a/java/com/android/dialer/common/concurrent/DialerExecutor.java b/java/com/android/dialer/common/concurrent/DialerExecutor.java
index 0414581d4..3ee06445f 100644
--- a/java/com/android/dialer/common/concurrent/DialerExecutor.java
+++ b/java/com/android/dialer/common/concurrent/DialerExecutor.java
@@ -25,7 +25,95 @@ import java.util.concurrent.ExecutorService;
 /**
  * Provides a consistent interface for doing background work in either UI or non-UI contexts.
  *
- * <p>See {@link DialerExecutors} for usage examples.
+ * <p>You may create an executor from a UI component (activity or fragment) or a non-UI component.
+ * Using this class provides a number of benefits:
+ *
+ * <ul>
+ *   <li>Ensures that UI tasks keep running across configuration changes by using a headless
+ *       fragment.
+ *   <li>Forces exceptions to crash the application, unless the user implements their own onFailure
+ *       method.
+ *   <li>Checks for dead UI components which can be encountered if a UI task runs longer than its
+ *       UI. If a dead UI component is encountered, onSuccess/onFailure are not called (because they
+ *       can't be) but a message is logged.
+ *   <li>Helps prevent memory leaks in UI tasks by ensuring that callbacks are nulled out when the
+ *       headless fragment is detached.
+ *   <li>UI and non-UI threads are shared across the application and run at reasonable priorities
+ * </ul>
+ *
+ * <p>Executors accept a single input and output parameter which should be immutable data objects.
+ * If you don't require an input or output, use Void and null as needed.
+ *
+ * <p>You may optionally specify onSuccess and onFailure listeners; the default behavior on success
+ * is a no-op and the default behavior on failure is to crash the application.
+ *
+ * <p>To use an executor from a UI component, you must create it in your onCreate method and then
+ * use it from anywhere:
+ *
+ * <pre><code>
+ *
+ * public class MyActivity extends Activity {
+ *
+ *   private final DialerExecutor&lt;MyInputType&gt; myExecutor;
+ *
+ *   public void onCreate(Bundle state) {
+ *     super.onCreate(bundle);
+ *
+ *     // Must be called in onCreate; don't use non-static or anonymous inner classes for worker!
+ *     myExecutor = DialerExecutorComponent.get(context).dialerExecutorFactory()
+ *         .createUiTaskBuilder(fragmentManager, taskId, worker)
+ *         .onSuccess(this::onSuccess)  // Lambdas, anonymous, or non-static inner classes all fine
+ *         .onFailure(this::onFailure)  // Lambdas, anonymous, or non-static inner classes all fine
+ *         .build();
+ *     );
+ *   }
+ *
+ *   private static class MyWorker implements Worker&lt;MyInputType, MyOutputType&gt; {
+ *     MyOutputType doInBackground(MyInputType input) { ... }
+ *   }
+ *   private void onSuccess(MyOutputType output) { ... }
+ *   private void onFailure(Throwable throwable) { ... }
+ *
+ *   private void userDidSomething() { myExecutor.executeParallel(input); }
+ * }
+ * </code></pre>
+ *
+ * <p>Usage for non-UI tasks is the same, except that tasks can be created from anywhere instead of
+ * in onCreate. Non-UI tasks use low-priority threads separate from the UI task threads so as not to
+ * compete with more critical UI tasks.
+ *
+ * <pre><code>
+ *
+ * public class MyManager {
+ *
+ *   private final DialerExecutor&lt;MyInputType&gt; myExecutor;
+ *
+ *   public void init() {
+ *     // Don't use non-static or anonymous inner classes for worker!
+ *     myExecutor = DialerExecutorComponent.get(context).dialerExecutorFactory()
+ *         .createNonUiTaskBuilder(worker)
+ *         .onSuccess(this::onSuccess)  // Lambdas, anonymous, or non-static inner classes all fine
+ *         .onFailure(this::onFailure)  // Lambdas, anonymous, or non-static inner classes all fine
+ *         .build();
+ *     );
+ *   }
+ *
+ *   private static class MyWorker implements Worker&lt;MyInputType, MyOutputType&gt; {
+ *     MyOutputType doInBackground(MyInputType input) { ... }
+ *   }
+ *   private void onSuccess(MyOutputType output) { ... }
+ *   private void onFailure(Throwable throwable) { ... }
+ *
+ *   private void userDidSomething() { myExecutor.executeParallel(input); }
+ * }
+ * </code></pre>
+ *
+ * Note that non-UI tasks are intended to be relatively quick; for example reading/writing shared
+ * preferences or doing simple database work. If you submit long running non-UI tasks you may
+ * saturate the shared application threads and block other tasks. Also, this class does not create
+ * any wakelocks, so a long running task could be killed if the device goes to sleep while your task
+ * is still running. If you have to do long running or periodic work, consider using a job
+ * scheduler.
  */
 public interface DialerExecutor<InputT> {