/*
* 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.
*
*
See {@link DialerExecutors} for usage examples.
*/
public interface DialerExecutor {
/** Functional interface for doing work in the background. */
interface Worker {
@WorkerThread
@Nullable
OutputT doInBackground(@Nullable InputT input) throws Throwable;
}
/** Functional interface for handling the result of background work. */
interface SuccessListener {
@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 {
/**
* 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 onSuccess(@NonNull SuccessListener 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 onFailure(@NonNull FailureListener failureListener);
/**
* Builds the {@link DialerExecutor} which can be used to execute your task (repeatedly with
* differing inputs if desired).
*/
@NonNull
DialerExecutor build();
}
/** Executes the task such that repeated executions for this executor are serialized. */
@MainThread
void executeSerial(@Nullable InputT input);
/**
* 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);
}