src/main/java/com/google/devtools/build/lib/packages/BuiltinProvider.java

// Copyright 2018 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.packages;

import com.google.common.collect.ImmutableList;
import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable;
import com.google.devtools.build.lib.util.Fingerprint;
import javax.annotation.Nullable;
import net.starlark.java.annot.StarlarkBuiltin;
import net.starlark.java.eval.Printer;
import net.starlark.java.eval.Starlark;
import net.starlark.java.eval.StarlarkSemantics;
import net.starlark.java.syntax.Location;
import net.starlark.java.syntax.StarlarkType;
import net.starlark.java.syntax.TypeConstructor;
import net.starlark.java.syntax.Types;

/**
 * Base class for declared providers {@see Provider} built into Blaze.
 *
 * <p>Every subclass of {@link BuiltinProvider} should have exactly one instance. If multiple
 * instances of the same subclass are instantiated, they are considered equivalent. This design is
 * motivated by the need for serialization. Starlark providers are readily identified by the pair
 * (.bzl file name, sequence number during execution). BuiltinProviders need an analogous
 * serializable identifier, yet JVM classes (notoriously) don't have a predictable initialization
 * order, so we can't use a sequence number. A distinct subclass for each built-in provider acts as
 * that identifier.
 *
 * <p>Implementations of native declared providers should subclass this class, and define a method
 * in the subclass definition to create instances of its corresponding Info object. The method
 * should be annotated with {@link StarlarkMethod} with {@link StarlarkMethod#selfCall} set to true,
 * and with {@link StarlarkConstructor} for the info type it constructs.
 *
 * <p>Implementations that are not callable from Starlark typically should subclass {@link
 * BuiltinProvider.NonCallable}. (The exception is if a non-callable provider needs a custom {@link
 * StarlarkBuiltin}-annotated interface; see {@link BuiltinProvider.NonCallable} documentation below
 * for details.)
 */
@Immutable
public abstract class BuiltinProvider<T extends Info> implements Provider, TypeConstructor {
  private final Key key;
  private final String name;
  private final Class<T> valueClass;
  private final StarlarkType valueType;

  protected BuiltinProvider(String name, Class<T> valueClass) {
    this.key = new Key(name, getClass());
    this.name = name;
    this.valueClass = valueClass;
    this.valueType = Starlark.getStarlarkTypeFromJavaType(valueClass, /* objectIsAny= */ false);
  }

  public Class<T> getValueClass() {
    return valueClass;
  }

  /**
   * Defines the equivalence relation: all BuiltinProviders of the same Java class are equal,
   * regardless of {@code name} or {@code valueClass}.
   */
  @Override
  public final boolean equals(@Nullable Object other) {
    return other != null && this.getClass().equals(other.getClass());
  }

  @Override
  public final int hashCode() {
    return getClass().getName().hashCode();
  }

  @Override
  public void checkHashable() {
    // The hash code is based on the class, so it is hashable.
  }

  @Override
  public boolean isExported() {
    return true;
  }

  @Override
  public Key getKey() {
    return key;
  }

  @Override
  public Location getLocation() {
    return Location.BUILTIN;
  }

  @Override
  public String getPrintableName() {
    return name;
  }

  @Override
  public void repr(Printer printer, StarlarkSemantics semantics) {
    // TODO(adonovan): change to '<provider name>'.
    printer.append("<function " + name + ">");
  }

  /** Returns the identifier of this provider. */
  public StarlarkProviderIdentifier id() {
    return StarlarkProviderIdentifier.forKey(key);
  }

  /** Returns the Starlark type of the {@link Info} instances that this provider constructs. */
  @Override
  public StarlarkType createStarlarkType(ImmutableList<Term> argsTuple)
      throws TypeConstructor.Failure {
    if (!argsTuple.isEmpty()) {
      throw new TypeConstructor.Failure(
          String.format("'%s' does not accept arguments", getPrintableName()));
    }
    return valueType;
  }

  /**
   * Convenience class for subclassing {@link BuiltinProvider}s that cannot be called from Starlark.
   *
   * <p>Exception: since {@link BuiltinProvider.NonCallable} is annotated as a {@link
   * StarlarkBuiltin}, non-callable providers with custom {@link StarlarkBuiltin}-annotated
   * interfaces should not subclass it. Instead, such providers can subclass {@link BuiltinProvider}
   * directly. To ensure that such a provider is typed correctly, the {@link StarlarkBuiltin}-
   * annotated interface needs to extend {@link ProviderApi} and have a static {@code
   * getStarlarkType()} method that returns the appropriate type ({@link Types#TYPE} or a subtype of
   * it). Example: {@code AnalysisFailureInfoProvider}.
   */
  @StarlarkBuiltin(name = "Provider", documented = false, doc = "")
  public abstract static class NonCallable<T extends Info> extends BuiltinProvider<T> {
    protected NonCallable(String name, Class<T> valueClass) {
      super(name, valueClass);
    }

    public static StarlarkType getStarlarkType() {
      // Just a reified type, not a Callable, since it does not act as a constructor.
      return Types.TYPE;
    }
  }

  /** A serializable reference to a {@link BuiltinProvider}. */
  @Immutable
  public static final class Key extends Provider.Key {
    private final String name;
    private final Class<? extends Provider> providerClass;

    public Key(String name, Class<? extends Provider> providerClass) {
      this.name = name;
      this.providerClass = providerClass;
    }

    public String getName() {
      return name;
    }

    public Class<? extends Provider> getProviderClass() {
      return providerClass;
    }

    @Override
    void fingerprint(Fingerprint fp) {
      // True => native
      fp.addBoolean(true);
      fp.addString(name);
    }

    @Override
    public int hashCode() {
      return providerClass.getName().hashCode();
    }

    @Override
    public boolean equals(Object obj) {
      return obj instanceof Key && providerClass.equals(((Key) obj).providerClass);
    }

    @Override
    public String toString() {
      return name;
    }
  }
}