1 /*
2  * Copyright (C) 2016 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.incallui.async;
18 
19 import com.android.contacts.common.testing.NeededForTesting;
20 
21 import java.util.concurrent.Executor;
22 
23 /**
24  * Executor that can be used to easily synchronize testing and production code. Production code
25  * should call {@link #milestone()} at points in the code where the state of the system is worthy of
26  * testing. In a test scenario, this method will pause execution until the test acknowledges the
27  * milestone through the use of {@link #ackMilestoneForTesting()}.
28  */
29 public interface PausableExecutor extends Executor {
30 
31     /**
32      * Method called from asynchronous production code to inform this executor that it has
33      * reached a point that puts the system into a state worth testing. TestableExecutors intended
34      * for use in a testing environment should cause the calling thread to block. In the production
35      * environment this should be a no-op.
36      */
milestone()37     void milestone();
38 
39     /**
40      * Method called from the test code to inform this executor that the state of the production
41      * system at the current milestone has been sufficiently tested. Every milestone must be
42      * acknowledged.
43      */
44     @NeededForTesting
ackMilestoneForTesting()45     void ackMilestoneForTesting();
46 
47     /**
48      * Method called from the test code to inform this executor that the tests are finished with all
49      * milestones. Future calls to {@link #milestone()} or {@link #awaitMilestoneForTesting()}
50      * should return immediately.
51      */
52     @NeededForTesting
ackAllMilestonesForTesting()53     void ackAllMilestonesForTesting();
54 
55     /**
56      * Method called from the test code to block until a milestone has been reached in the
57      * production code.
58      */
59     @NeededForTesting
awaitMilestoneForTesting()60     void awaitMilestoneForTesting() throws InterruptedException;
61 }
62