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
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
// Copyright 2014 The Bazel Authors. All rights reserved.
//
// 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.google.devtools.build.skyframe;
import com.google.devtools.build.lib.concurrent.ThreadSafety;
import java.util.function.Supplier;
import javax.annotation.Nullable;
/** Receiver for various stages of the lifetime of a skyframe node evaluation. */
@ThreadSafety.ThreadSafe
public interface EvaluationProgressReceiver {
/**
* New state of the value entry after evaluation.
*/
enum EvaluationState {
/** The value was successfully re-evaluated. */
BUILT,
/** The value is clean or re-validated. */
CLEAN,
}
/** Whether or not evaluation of this node succeeded. */
enum EvaluationSuccessState {
SUCCESS(true),
FAILURE(false);
EvaluationSuccessState(boolean succeeded) {
this.succeeded = succeeded;
}
private final boolean succeeded;
public boolean succeeded() {
return succeeded;
}
public Supplier<EvaluationSuccessState> supplier() {
return () -> this;
}
}
/**
* New state of the value entry after invalidation.
*/
enum InvalidationState {
/** The value is dirty, although it might get re-validated again. */
DIRTY,
/** The value is dirty and got deleted, cannot get re-validated again. */
DELETED,
}
/**
* Overall state of the node while it is being evaluated.
*/
enum NodeState {
/** The node is undergoing a dirtiness check and may be re-validated. */
CHECK_DIRTY,
/** The node is prepping for evaluation. */
INITIALIZING_ENVIRONMENT,
/** The node is in compute(). */
COMPUTE,
/** The node is done evaluation and committing the result. */
COMMIT,
}
/**
* Notifies that the node named by {@code key} has been invalidated.
*
* <p>{@code state} indicates the new state of the value.
*
* <p>May be called concurrently from multiple threads, possibly with the same {@code key}.
*/
void invalidated(SkyKey skyKey, InvalidationState state);
/**
* Notifies that {@code skyKey} is about to get queued for evaluation.
*
* <p>Note that we don't guarantee that it actually got enqueued or will, only that if
* everything "goes well" (e.g. no interrupts happen) it will.
*
* <p>This guarantee is intentionally vague to encourage writing robust implementations.
*/
void enqueueing(SkyKey skyKey);
/**
* Notifies that a node corresponding to {@code skyKey} is about to enter the given
* {@code nodeState}.
*
* <p>Notably, this includes {@link SkyFunction#compute} calls due to Skyframe restarts, but also
* dirtiness checking and node completion.
*/
void stateStarting(SkyKey skyKey, NodeState nodeState);
/**
* Notifies that a node corresponding to {@code skyKey} is about to complete the given
* {@code nodeState}.
*
* <p>Always called symmetrically with {@link #stateStarting(SkyKey, NodeState)}}.
*
* <p>{@code elapsedTimeNanos} is either the elapsed time in the {@code nodeState} or -1 if the
* timing was not recorded.
*/
void stateEnding(SkyKey skyKey, NodeState nodeState, long elapsedTimeNanos);
/**
* Notifies that the node for {@code skyKey} has been evaluated.
*
* <p>{@code state} indicates the new state of the node.
*
* <p>If the value builder threw an error when building this node, then {@code
* valueSupplier.get()} evaluates to null.
*
* @param value The sky value. Only available if just evaluated, eg. on success *and* <code>
* state == EvalutionState.BUILT</code>
*/
void evaluated(
SkyKey skyKey,
@Nullable SkyValue value,
Supplier<EvaluationSuccessState> evaluationSuccessState,
EvaluationState state);
/** An {@link EvaluationProgressReceiver} that does nothing. */
class NullEvaluationProgressReceiver implements EvaluationProgressReceiver {
@Override
public void invalidated(SkyKey skyKey, InvalidationState state) {
}
@Override
public void enqueueing(SkyKey skyKey) {
}
@Override
public void stateStarting(SkyKey skyKey, NodeState nodeState) {
}
@Override
public void stateEnding(SkyKey skyKey, NodeState nodeState, long elapsedTimeNanos) {
}
@Override
public void evaluated(
SkyKey skyKey,
@Nullable SkyValue value,
Supplier<EvaluationSuccessState> evaluationSuccessState,
EvaluationState state) {}
}
}
|
