Home | History | Annotate | Download | only in concurrent 
      1 /*
      2  * Copyright (C) 2017 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License
     15  */
     16 
     17 package com.android.dialer.common.concurrent;
     18 
     19 import android.support.annotation.MainThread;
     20 import android.support.annotation.NonNull;
     21 import android.support.annotation.Nullable;
     22 import android.support.annotation.WorkerThread;
     23 import java.util.concurrent.ExecutorService;
     24 
     25 /**
     26  * Provides a consistent interface for doing background work in either UI or non-UI contexts.
     27  *
     28  * <p>See {@link DialerExecutors} for usage examples.
     29  */
     30 public interface DialerExecutor<InputT> {
     31 
     32   /** Functional interface for doing work in the background. */
     33   interface Worker<InputT, OutputT> {
     34     @WorkerThread
     35     @Nullable
     36     OutputT doInBackground(@Nullable InputT input) throws Throwable;
     37   }
     38 
     39   /** Functional interface for handling the result of background work. */
     40   interface SuccessListener<OutputT> {
     41     @MainThread
     42     void onSuccess(@Nullable OutputT output);
     43   }
     44 
     45   /** Functional interface for handling an error produced while performing background work. */
     46   interface FailureListener {
     47     @MainThread
     48     void onFailure(@NonNull Throwable throwable);
     49   }
     50 
     51   /** Builder for {@link DialerExecutor}. */
     52   interface Builder<InputT, OutputT> {
     53 
     54     /**
     55      * Optional. Default is no-op.
     56      *
     57      * @param successListener a function executed on the main thread upon task success. There are no
     58      *     restraints on this as it is executed on the main thread, so lambdas, anonymous, or inner
     59      *     classes of your activity or fragment are all fine.
     60      */
     61     @NonNull
     62     Builder<InputT, OutputT> onSuccess(@NonNull SuccessListener<OutputT> successListener);
     63 
     64     /**
     65      * Optional. If this is not set and your worker throws an exception, the application will crash.
     66      *
     67      * @param failureListener a function executed on the main thread upon task failure. There are no
     68      *     restraints on this as it is executed on the main thread, so lambdas, anonymous, or inner
     69      *     classes of your activity or fragment are all fine.
     70      */
     71     @NonNull
     72     Builder<InputT, OutputT> onFailure(@NonNull FailureListener failureListener);
     73 
     74     /**
     75      * Builds the {@link DialerExecutor} which can be used to execute your task (repeatedly with
     76      * differing inputs if desired).
     77      */
     78     @NonNull
     79     DialerExecutor<InputT> build();
     80   }
     81 
     82   /** Executes the task such that repeated executions for this executor are serialized. */
     83   @MainThread
     84   void executeSerial(@Nullable InputT input);
     85 
     86   /**
     87    * Executes the task after waiting {@code waitMillis}. If called while the previous invocation is
     88    * still waiting to be started, the original invocation is cancelled.
     89    *
     90    * <p>This is useful for tasks which might get scheduled many times in very quick succession, but
     91    * it is only the last one that actually needs to be executed.
     92    */
     93   @MainThread
     94   void executeSerialWithWait(@Nullable InputT input, long waitMillis);
     95 
     96   /**
     97    * Executes the task on a thread pool shared across the application. Multiple calls using this
     98    * method may result in tasks being executed in parallel.
     99    */
    100   @MainThread
    101   void executeParallel(@Nullable InputT input);
    102 
    103   /**
    104    * Executes the task on a custom executor service. This should rarely be used; instead prefer
    105    * {@link #executeSerial(Object)} or {@link #executeParallel(Object)}.
    106    */
    107   @MainThread
    108   void executeOnCustomExecutorService(
    109       @NonNull ExecutorService executorService, @Nullable InputT input);
    110 }
    111