1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
|
/*
* 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.support.annotation.MainThread;
import android.support.annotation.NonNull;
import android.support.annotation.Nullable;
import android.support.annotation.WorkerThread;
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.
*/
public interface DialerExecutor<InputT> {
/** Functional interface for doing work in the background. */
interface Worker<InputT, OutputT> {
@WorkerThread
@Nullable
OutputT doInBackground(@Nullable InputT input) throws Throwable;
}
/** Functional interface for handling the result of background work. */
interface SuccessListener<OutputT> {
@MainThread
void onSuccess(@Nullable OutputT output);
}
/** Functional interface for handling an error produced while performing background work. */
interface FailureListener {
@MainThread
void onFailure(@NonNull Throwable throwable);
}
/** Builder for {@link DialerExecutor}. */
interface Builder<InputT, OutputT> {
/**
* Optional. Default is no-op.
*
* @param successListener a function executed on the main thread upon task success. There are no
* restraints on this as it is executed on the main thread, so lambdas, anonymous, or inner
* classes of your activity or fragment are all fine.
*/
@NonNull
Builder<InputT, OutputT> onSuccess(@NonNull SuccessListener<OutputT> successListener);
/**
* Optional. If this is not set and your worker throws an exception, the application will crash.
*
* @param failureListener a function executed on the main thread upon task failure. There are no
* restraints on this as it is executed on the main thread, so lambdas, anonymous, or inner
* classes of your activity or fragment are all fine.
*/
@NonNull
Builder<InputT, OutputT> onFailure(@NonNull FailureListener failureListener);
/**
* Builds the {@link DialerExecutor} which can be used to execute your task (repeatedly with
* differing inputs if desired).
*/
@NonNull
DialerExecutor<InputT> build();
}
/** Executes the task such that repeated executions for this executor are serialized. */
@MainThread
void executeSerial(@Nullable InputT input);
/**
* Executes the task after waiting {@code waitMillis}. If called while the previous invocation is
* still waiting to be started, the original invocation is cancelled.
*
* <p>This is useful for tasks which might get scheduled many times in very quick succession, but
* it is only the last one that actually needs to be executed.
*/
@MainThread
void executeSerialWithWait(@Nullable InputT input, long waitMillis);
/**
* Executes the task on a thread pool shared across the application. Multiple calls using this
* method may result in tasks being executed in parallel.
*/
@MainThread
void executeParallel(@Nullable InputT input);
/**
* Executes the task on a custom executor service. This should rarely be used; instead prefer
* {@link #executeSerial(Object)} or {@link #executeParallel(Object)}.
*/
@MainThread
void executeOnCustomExecutorService(
@NonNull ExecutorService executorService, @Nullable InputT input);
}
|