/* * Copyright (C) 2017 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License */ package com.android.dialer.common.concurrent; import android.app.FragmentManager; import android.support.annotation.NonNull; import com.android.dialer.common.Assert; import com.android.dialer.common.LogUtil; import com.android.dialer.common.concurrent.DialerExecutor.Worker; import java.util.concurrent.ExecutorService; import java.util.concurrent.Executors; import java.util.concurrent.ThreadFactory; /** * Factory methods for creating {@link DialerExecutor} objects for doing background work. * *
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: * *
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. * *
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. * *
To use an executor from a UI component, you must create it in your onCreate method and then * use it from anywhere: * *
*
* public class MyActivity extends Activity {
*
* private final DialerExecutor<MyInputType> 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 = DialerExecutors.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<MyInputType, MyOutputType> {
* MyOutputType doInBackground(MyInputType input) { ... }
* }
* private void onSuccess(MyOutputType output) { ... }
* private void onFailure(Throwable throwable) { ... }
*
* private void userDidSomething() { myExecutor.executeParallel(input); }
* }
*
*
* 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. * *
*
* public class MyManager {
*
* private final DialerExecutor<MyInputType> myExecutor;
*
* public void init() {
* // Don't use non-static or anonymous inner classes for worker!
* myExecutor = DialerExecutors.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<MyInputType, MyOutputType> {
* MyOutputType doInBackground(MyInputType input) { ... }
* }
* private void onSuccess(MyOutputType output) { ... }
* private void onFailure(Throwable throwable) { ... }
*
* private void userDidSomething() { myExecutor.executeParallel(input); }
* }
*
*
* 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 final class DialerExecutors {
/** @see DialerExecutorFactory#createUiTaskBuilder(FragmentManager, String, Worker) */
@NonNull
public static This exists to prevent each individual dialer component from having to create its own * threads/pools, which would result in the application having more threads than really necessary. */ public static ExecutorService getLowPriorityThreadPool() { return lowPriorityThreadPool; } }