| // Copyright 2022 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 java.util.NoSuchElementException; |
| import javax.annotation.Nullable; |
| |
| /** |
| * An iterable-like result of getting Skyframe dependencies via {@link |
| * SkyFunction.Environment#getOrderedValuesAndExceptions}. Callers can use the {@link #next} and |
| * {@link #nextOrThrow} methods to obtain successive elements. |
| * |
| * <p>Can only be iterated through once: if an iterable of size k was passed to {@link |
| * SkyFunction.Environment#getOrderedValuesAndExceptions}, then the returned {@link |
| * SkyframeIterableResult} can have {@link #next} and {@link #nextOrThrow} called a total of k |
| * times. |
| * |
| * <p>Note that a {@link SkyFunction} cannot guarantee that {@link |
| * SkyFunction.Environment#valuesMissing} will be true upon receipt of a {@code |
| * SkyframeIterableResult}. The elements must be iterated over. If {@link #next} or {@link |
| * #nextOrThrow} returns {@code null}, only then will {@link SkyFunction.Environment#valuesMissing} |
| * be guaranteed to return true. |
| */ |
| public interface SkyframeIterableResult { |
| |
| /** |
| * Returns true if {@link SkyframeIterableResult} has more elements. In other words, returns true |
| * if {@link #next} or {@link #nextOrThrow} would return an element rather than throwing a {@link |
| * NoSuchElementException}. |
| */ |
| boolean hasNext(); |
| |
| /** |
| * Returns the next direct dependency in {@link SkyframeIterableResult}. If the dependency is not |
| * in the set of already evaluated direct dependencies, returns {@code null}. Also returns {@code |
| * null} if the dependency has already been evaluated and found to be in error. In either of these |
| * cases, {@link SkyFunction.Environment#valuesMissing} will subsequently return true. |
| */ |
| @Nullable |
| default SkyValue next() { |
| return nextOrThrow(null, null, null); |
| } |
| |
| /** |
| * Returns the next direct dependency in {@link SkyframeIterableResult}. If the dependency is not |
| * in the set of already evaluated direct dependencies, returns {@code null}. If the dependency |
| * has already been evaluated and found to be in error, throws the exception coming from the |
| * error, so long as the exception is of one of the specified types. SkyFunction implementations |
| * may use this method to catch and rethrow a more informative exception or to continue |
| * evaluation. The caller must specify the exception type(s) that might be thrown using the {@code |
| * exceptionClass} argument(s). If the dependency's exception is not an instance of {@code |
| * exceptionClass}, {@code null} is returned. In this case, {@link |
| * SkyFunction.Environment#valuesMissing} will subsequently return true. |
| * |
| * <p>The exception class given cannot be a supertype or a subtype of {@link RuntimeException}, or |
| * a subtype of {@link InterruptedException}. See {@link |
| * SkyFunctionException#validateExceptionType} for details. |
| */ |
| @Nullable |
| default <E extends Exception> SkyValue nextOrThrow(Class<E> exceptionClass) throws E { |
| return nextOrThrow(exceptionClass, null, null, null); |
| } |
| |
| @Nullable |
| default <E1 extends Exception, E2 extends Exception> SkyValue nextOrThrow( |
| Class<E1> exceptionClass1, Class<E2> exceptionClass2) throws E1, E2 { |
| return nextOrThrow(exceptionClass1, exceptionClass2, null, null); |
| } |
| |
| @Nullable |
| default <E1 extends Exception, E2 extends Exception, E3 extends Exception> SkyValue nextOrThrow( |
| Class<E1> exceptionClass1, Class<E2> exceptionClass2, Class<E3> exceptionClass3) |
| throws E1, E2, E3 { |
| return nextOrThrow(exceptionClass1, exceptionClass2, exceptionClass3, null); |
| } |
| |
| @Nullable |
| <E1 extends Exception, E2 extends Exception, E3 extends Exception, E4 extends Exception> |
| SkyValue nextOrThrow( |
| @Nullable Class<E1> exceptionClass1, |
| @Nullable Class<E2> exceptionClass2, |
| @Nullable Class<E3> exceptionClass3, |
| @Nullable Class<E4> exceptionClass4) |
| throws E1, E2, E3, E4; |
| } |