// 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.lib.actions;

import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;
import com.google.devtools.build.lib.analysis.platform.PlatformInfo;
import com.google.devtools.build.lib.collect.nestedset.NestedSet;
import java.util.Collection;
import javax.annotation.Nullable;

/**
 * An object representing a subprocess to be invoked, including its command and
 * arguments, its working directory, its environment, a boolean indicating
 * whether remote execution is appropriate for this command, and if so, the set
 * of files it is expected to read and write.
 */
public interface Spawn {
  /**
   * Out-of-band data for this spawn. This can be used to signal hints (hardware requirements,
   * local vs. remote) to the execution subsystem.
   *
   * <p>String tags from {@link
   * com.google.devtools.build.lib.analysis.test.TestTargetProperties#getExecutionInfo()} can be added
   * as keys with arbitrary values to this map too.
   */
  ImmutableMap<String, String> getExecutionInfo();

  /**
   * Returns the {@link RunfilesSupplier} helper encapsulating the runfiles for this spawn.
   */
  RunfilesSupplier getRunfilesSupplier();

  /**
   * Returns the command (the first element) and its arguments.
   */
  ImmutableList<String> getArguments();

  /**
   * Returns the initial environment of the process.
   * If null, the environment is inherited from the parent process.
   */
  ImmutableMap<String, String> getEnvironment();

  /**
   * Map of the execpath at which we expect the Fileset symlink trees, to a list of
   * FilesetOutputSymlinks which contains the details of the Symlink trees.
   */
  ImmutableMap<Artifact, ImmutableList<FilesetOutputSymlink>> getFilesetMappings();

  /**
   * Returns the list of files that are required to execute this spawn (e.g. the compiler binary),
   * in contrast to files necessary for the tool to do its work (e.g. source code to be compiled).
   *
   * <p>The returned set of files is a subset of what getInputFiles() returns.
   *
   * <p>This method explicitly does not expand middleman artifacts. Pass the result to an
   * appropriate utility method on {@link com.google.devtools.build.lib.actions.Artifact} to expand
   * the middlemen.
   *
   * <p>This is for use with persistent workers, so we can restart workers when their binaries have
   * changed.
   */
  NestedSet<? extends ActionInput> getToolFiles();

  /**
   * Returns the list of files that this command may read.
   *
   * <p>This method explicitly does not expand middleman artifacts. Pass the result to an
   * appropriate utility method on {@link com.google.devtools.build.lib.actions.Artifact} to expand
   * the middlemen.
   *
   * <p>This is for use with remote execution, so we can ship inputs before starting the command.
   * Order stability across multiple calls should be upheld for performance reasons.
   */
  NestedSet<? extends ActionInput> getInputFiles();

  /**
   * Returns the collection of files that this command must write.  Callers should not mutate
   * the result.
   *
   * <p>This is for use with remote execution, so remote execution does not have to guess what
   * outputs the process writes.  While the order does not affect the semantics, it should be
   * stable so it can be cached.
   */
  Collection<? extends ActionInput> getOutputFiles();

  /**
   * Returns the resource owner for local fallback.
   */
  ActionExecutionMetadata getResourceOwner();

  /**
   * Returns the amount of resources needed for local fallback.
   */
  ResourceSet getLocalResources();

  /**
   * Returns a mnemonic (string constant) for this kind of spawn.
   */
  String getMnemonic();

  /**
   * Returns execution properties related to this spawn.
   *
   * <p>Note that this includes data from the execution platform's exec_properties as well as
   * target-level exec_properties.
   */
  ImmutableMap<String, String> getCombinedExecProperties();

  @Nullable
  PlatformInfo getExecutionPlatform();
}

@@ -1369,19 +1369,19 @@
 nts,
-%0A   *
  local
+%0A   *
  vs.
@@ -1420,23 +1420,310 @@
 tem.
-%0A   *%0A   * %3Cp%3ES
+ This data can come from multiple places e.g. tags, hard%0A   * coded into rule logic, etc.%0A   *%0A   * %3Cp%3EThe data in this field can be in one of two forms and it is up to the caller of this method%0A   * to extract the data it cares about. Forms:%0A   *%0A   * %3Cul%3E%0A   *   %3Cli%3Etrue key-value pairs%0A   *   %3Cli%3Es
 trin
@@ -1740,21 +1740,29 @@
 m %7B@link
+ *
 %0A   *
+      
  com.goo
@@ -1838,16 +1838,33 @@
 nInfo()%7D
+%0A   *       which
  can be 
@@ -1868,21 +1868,27 @@
 be added
-%0A   *
+ to the map
  as keys
@@ -1914,23 +1914,202 @@
 ues 
-to this map too
+(canonically the empty%0A   *       string)%0A   * %3C/ul%3E%0A   *%0A   * %3Cp%3ECallers of this method may also be interested in the %7B@link #getCombinedExecProperties()%7D.%0A   * See its javadoc for a comparison
 .%0A  
@@ -4999,24 +4999,268 @@
 properties.%0A
+   *%0A   * %3Cp%3ECallers might also be interested in %7B@link #getExecutionInfo()%7D above. %7B@link%0A   * #getExecutionInfo()%7D can be set by multiple sources while this data is set via the %7B@code%0A   * exec_properties%7D attribute on targets and platforms.%0A
    */%0A  Immu

Document the difference between Spawn#getExecutionInfo and Spawn#getCombinedExecProperties