Update getValues documentation to highlight impact of multiple getValue calls.
RELNOTES: None
PiperOrigin-RevId: 307050206
diff --git a/src/main/java/com/google/devtools/build/skyframe/SkyFunction.java b/src/main/java/com/google/devtools/build/skyframe/SkyFunction.java
index 45b64ce..61643a6 100644
--- a/src/main/java/com/google/devtools/build/skyframe/SkyFunction.java
+++ b/src/main/java/com/google/devtools/build/skyframe/SkyFunction.java
@@ -27,13 +27,13 @@
/**
* Machinery to evaluate a single value.
*
- * <p>The SkyFunction {@link #compute} implementation is supposed to access only direct
- * dependencies of the value. However, the direct dependencies need not be known in advance. The
- * implementation can request arbitrary values using {@link Environment#getValue}. If the values
- * are not ready, the call will return {@code null}; in that case the implementation should just
- * return {@code null}, in which case the missing dependencies will be computed and the {@link
- * #compute} method will be started again.
- * */
+ * <p>The SkyFunction {@link #compute} implementation is supposed to access only direct dependencies
+ * of the value. However, the direct dependencies need not be known in advance. The implementation
+ * can request arbitrary values using {@link Environment#getValue}. If the values are not ready, the
+ * call will return {@code null}; in that case the implementation should just return {@code null},
+ * in which case the missing dependencies will be computed and the {@link #compute} method will be
+ * started again.
+ */
public interface SkyFunction {
/**
@@ -67,10 +67,9 @@
/**
* Extracts a tag (target label) from a SkyKey if it has one. Otherwise return {@code null}.
*
- * <p>The tag is used for filtering out non-error event messages that do not match
- * --output_filter flag. If a SkyFunction returns {@code null} in this method it means that all
- * the info/warning messages associated with this value will be shown, no matter what
- * --output_filter says.
+ * <p>The tag is used for filtering out non-error event messages that do not match --output_filter
+ * flag. If a SkyFunction returns {@code null} in this method it means that all the info/warning
+ * messages associated with this value will be shown, no matter what --output_filter says.
*/
@Nullable
String extractTag(SkyKey skyKey);
@@ -196,14 +195,18 @@
* call, the two calls cannot be merged into a single getValues call, since the result of the
* first call might change on a later evaluation. Inversely, if the result of one getValue call
* cannot affect the parameters of the next getValue call, the two keys can form a dependency
- * group and the two getValue calls merged into one getValues call.
+ * group and the two getValue calls should be merged into one getValues call. In the latter
+ * case, if we fail to combine the _multiple_ getValue (or getValues) calls into one _single_
+ * getValues call, it would result in multiple dependency groups with an implicit ordering
+ * between them. This would unnecessarily cause sequential evaluations of these groups and could
+ * impact overall performance.
*
- * <p>This means that on subsequent evaluations, when checking to see if dependencies require
- * re-evaluation, all the values in this group may be simultaneously checked. A SkyFunction
- * should request a dependency group if checking the deps serially on a subsequent evaluation
- * would take too long, and if the {@link #compute} method would request all deps anyway as long
- * as no earlier deps had changed. SkyFunction.Environment implementations may also choose to
- * request these deps in parallel on the first evaluation, potentially speeding it up.
+ * <p>On subsequent evaluations, when checking to see if dependencies require re-evaluation, all
+ * the values within one group may be simultaneously checked. A SkyFunction should request a
+ * dependency group if checking the deps serially on a subsequent evaluation would take too
+ * long, and if the {@link #compute} method would request all deps anyway as long as no earlier
+ * deps had changed. SkyFunction.Environment implementations may also choose to request these
+ * deps in parallel on the first evaluation, potentially speeding it up.
*
* <p>While re-evaluating every value in the group may take longer than re-evaluating just the
* first one and finding that it has changed, no extra work is done: the contract of the
@@ -259,9 +262,10 @@
<E1 extends Exception, E2 extends Exception>
Map<SkyKey, ValueOrException2<E1, E2>> getValuesOrThrow(
- Iterable<? extends SkyKey> depKeys, Class<E1> exceptionClass1,
+ Iterable<? extends SkyKey> depKeys,
+ Class<E1> exceptionClass1,
Class<E2> exceptionClass2)
- throws InterruptedException;
+ throws InterruptedException;
<E1 extends Exception, E2 extends Exception, E3 extends Exception>
Map<SkyKey, ValueOrException3<E1, E2, E3>> getValuesOrThrow(
@@ -269,7 +273,7 @@
Class<E1> exceptionClass1,
Class<E2> exceptionClass2,
Class<E3> exceptionClass3)
- throws InterruptedException;
+ throws InterruptedException;
<E1 extends Exception, E2 extends Exception, E3 extends Exception, E4 extends Exception>
Map<SkyKey, ValueOrException4<E1, E2, E3, E4>> getValuesOrThrow(
@@ -278,7 +282,7 @@
Class<E2> exceptionClass2,
Class<E3> exceptionClass3,
Class<E4> exceptionClass4)
- throws InterruptedException;
+ throws InterruptedException;
<
E1 extends Exception,
@@ -293,19 +297,17 @@
Class<E3> exceptionClass3,
Class<E4> exceptionClass4,
Class<E5> exceptionClass5)
- throws InterruptedException;
+ throws InterruptedException;
/**
* Returns whether there was a previous getValue[s][OrThrow] that indicated a missing
* dependency. Formally, returns true iff at least one of the following occurred:
*
* <ul>
- * <li>getValue[OrThrow](k[, c]) returned {@code null} for some k</li>
- * <li>getValues(ks).get(k) == {@code null} for some ks and k such that ks.contains(k)</li>
- * <li>
- * getValuesOrThrow(ks, c).get(k).get() == {@code null} for some ks and k such that
- * ks.contains(k)
- * </li>
+ * <li>getValue[OrThrow](k[, c]) returned {@code null} for some k
+ * <li>getValues(ks).get(k) == {@code null} for some ks and k such that ks.contains(k)
+ * <li>getValuesOrThrow(ks, c).get(k).get() == {@code null} for some ks and k such that
+ * ks.contains(k)
* </ul>
*
* <p>If this returns true, the {@link SkyFunction} must return {@code null}.
