// 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.ThreadSafe;
import com.google.errorprone.annotations.CanIgnoreReturnValue;
import java.util.Map;
import javax.annotation.Nullable;
/**
* A graph that exposes its entries and structure, for use by classes that must traverse it.
*
*
Certain graph implementations can throw {@link InterruptedException} when trying to retrieve
* node entries. Such exceptions should not be caught locally -- they should be allowed to propagate
* up.
*/
@ThreadSafe
public interface QueryableGraph {
/**
* Returns the node with the given {@code key}, or {@code null} if the node does not exist.
*
* @param requestor if non-{@code null}, the node on behalf of which {@code key} is being
* requested.
* @param reason the reason the node is being requested.
*/
@Nullable
NodeEntry get(@Nullable SkyKey requestor, Reason reason, SkyKey key) throws InterruptedException;
/**
* Fetches all the given nodes. Returns a map {@code m} such that, for all {@code k} in {@code
* keys}, {@code m.get(k).equals(e)} iff {@code get(k) == e} and {@code e != null}, and {@code
* !m.containsKey(k)} iff {@code get(k) == null}.
*
* @param requestor if non-{@code null}, the node on behalf of which the given {@code keys} are
* being requested.
* @param reason the reason the nodes are being requested.
*/
Map getBatch(
@Nullable SkyKey requestor, Reason reason, Iterable extends SkyKey> keys)
throws InterruptedException;
/**
* A version of {@link #getBatch} that returns an {@link InterruptibleSupplier} to possibly
* retrieve the results later.
*/
@CanIgnoreReturnValue
default InterruptibleSupplier