Roll Observatory packages and add a roll script

analyzer/lib/task/model.dart

-// Copyright (c) 2015, the Dart project authors.  Please see the AUTHORS file
-// for details. All rights reserved. Use of this source code is governed by a
-// BSD-style license that can be found in the LICENSE file.
-
-library analyzer.task.model;
-
-import 'dart:collection';
-
-import 'package:analyzer/src/generated/engine.dart' hide AnalysisTask;
-import 'package:analyzer/src/generated/java_engine.dart';
-import 'package:analyzer/src/generated/source.dart';
-import 'package:analyzer/src/task/driver.dart';
-import 'package:analyzer/src/task/model.dart';
-
-/**
- * A function that converts the given [key] and [value] into a [TaskInput].
- */
-typedef TaskInput<E> BinaryFunction<K, V, E>(K key, V value);
-
-/**
- * A function that takes an analysis [context] and an analysis [target] and
- * returns an analysis task. Such functions are passed to a [TaskDescriptor] to
- * be used to create the described task.
- */
-typedef AnalysisTask BuildTask(AnalysisContext context, AnalysisTarget target);
-
-/**
- * A function that takes the target for which a task will produce results and
- * returns a map from input names to descriptions of the analysis results needed
- * by the task in order for the task to be performed. Such functions are passed
- * to a [TaskDescriptor] to be used to determine the inputs needed by the task.
- */
-typedef Map<String, TaskInput> CreateTaskInputs(AnalysisTarget target);
-
-/**
- * A function that converts an object of the type [B] into a [TaskInput].
- * This is used, for example, by a [ListTaskInput] to create task inputs
- * for each value in a list of values.
- */
-typedef TaskInput<E> UnaryFunction<B, E>(B object);
-
-/**
- * An [AnalysisTarget] wrapper for an [AnalysisContext].
- */
-class AnalysisContextTarget implements AnalysisTarget {
-  static final AnalysisContextTarget request = new AnalysisContextTarget(null);
-
-  final AnalysisContext context;
-
-  AnalysisContextTarget(this.context);
-
-  @override
-  Source get source => null;
-}
-
-/**
- * An object with which an analysis result can be associated.
- *
- * Clients are allowed to subtype this class when creating new kinds of targets.
- * Instances of this type are used in hashed data structures, so subtypes are
- * required to correctly implement [==] and [hashCode].
- */
-abstract class AnalysisTarget {
-  /**
-   * Return the source associated with this target, or `null` if this target is
-   * not associated with a source.
-   */
-  Source get source;
-}
-
-/**
- * An object used to compute one or more analysis results associated with a
- * single target.
- *
- * Clients are expected to extend this class when creating new tasks.
- */
-abstract class AnalysisTask {
-  /**
-   * A table mapping the types of analysis tasks to the number of times each
-   * kind of task has been performed.
-   */
-  static final Map<Type, int> countMap = new HashMap<Type, int>();
-
-  /**
-   * A table mapping the types of analysis tasks to stopwatches used to compute
-   * how much time was spent executing each kind of task.
-   */
-  static final Map<Type, Stopwatch> stopwatchMap =
-      new HashMap<Type, Stopwatch>();
-
-  /**
-   * The context in which the task is to be performed.
-   */
-  final AnalysisContext context;
-
-  /**
-   * The target for which result values are being produced.
-   */
-  final AnalysisTarget target;
-
-  /**
-   * A table mapping input names to input values.
-   */
-  Map<String, dynamic> inputs;
-
-  /**
-   * A table mapping result descriptors whose values are produced by this task
-   * to the values that were produced.
-   */
-  Map<ResultDescriptor, dynamic> outputs =
-      new HashMap<ResultDescriptor, dynamic>();
-
-  /**
-   * The exception that was thrown while performing this task, or `null` if the
-   * task completed successfully.
-   */
-  CaughtException caughtException;
-
-  /**
-   * If a dependency cycle was found while computing the inputs for the task,
-   * the set of [WorkItem]s contained in the cycle (if there are overlapping
-   * cycles, this is the set of all [WorkItem]s in the entire strongly
-   * connected component).  Otherwise, `null`.
-   */
-  List<WorkItem> dependencyCycle;
-
-  /**
-   * Initialize a newly created task to perform analysis within the given
-   * [context] in order to produce results for the given [target].
-   */
-  AnalysisTask(this.context, this.target);
-
-  /**
-   * Return a textual description of this task.
-   */
-  String get description;
-
-  /**
-   * Return the descriptor that describes this task.
-   */
-  TaskDescriptor get descriptor;
-
-  /**
-   * Indicates whether the task is capable of handling dependency cycles.  A
-   * task that overrides this getter to return `true` must be prepared for the
-   * possibility that it will be invoked with a non-`null` value of
-   * [dependencyCycle], and with not all of its inputs computed.
-   */
-  bool get handlesDependencyCycles => false;
-
-  /**
-   * Return the value of the input with the given [name]. Throw an exception if
-   * the input value is not defined.
-   */
-  Object getRequiredInput(String name) {
-    if (inputs == null || !inputs.containsKey(name)) {
-      throw new AnalysisException("Could not $description: missing $name");
-    }
-    return inputs[name];
-  }
-
-  /**
-   * Return the source associated with the target. Throw an exception if
-   * the target is not associated with a source.
-   */
-  Source getRequiredSource() {
-    Source source = target.source;
-    if (source == null) {
-      throw new AnalysisException("Could not $description: missing source");
-    }
-    return source;
-  }
-
-  /**
-   * Perform this analysis task, protected by an exception handler.
-   *
-   * This method should throw an [AnalysisException] if an exception occurs
-   * while performing the task. If other kinds of exceptions are thrown they
-   * will be wrapped in an [AnalysisException].
-   *
-   * If no exception is thrown, this method must fully populate the [outputs]
-   * map (have a key/value pair for each result that this task is expected to
-   * produce).
-   */
-  void internalPerform();
-
-  /**
-   * Perform this analysis task. When this method returns, either the [outputs]
-   * map should be fully populated (have a key/value pair for each result that
-   * this task is expected to produce) or the [caughtException] should be set.
-   *
-   * Clients should not override this method.
-   */
-  void perform() {
-    try {
-      _safelyPerform();
-    } on AnalysisException catch (exception, stackTrace) {
-      caughtException = new CaughtException(exception, stackTrace);
-      AnalysisEngine.instance.logger.logInformation(
-          "Task failed: ${description}", caughtException);
-    }
-  }
-
-  @override
-  String toString() => description;
-
-  /**
-   * Perform this analysis task, ensuring that all exceptions are wrapped in an
-   * [AnalysisException].
-   *
-   * Clients should not override this method.
-   */
-  void _safelyPerform() {
-    try {
-      //
-      // Report that this task is being performed.
-      //
-      String contextName = context.name;
-      if (contextName == null) {
-        contextName = 'unnamed';
-      }
-      AnalysisEngine.instance.instrumentationService.logAnalysisTask(
-          contextName, this);
-      //
-      // Gather statistics on the performance of the task.
-      //
-      int count = countMap[runtimeType];
-      countMap[runtimeType] = count == null ? 1 : count + 1;
-      Stopwatch stopwatch = stopwatchMap[runtimeType];
-      if (stopwatch == null) {
-        stopwatch = new Stopwatch();
-        stopwatchMap[runtimeType] = stopwatch;
-      }
-      stopwatch.start();
-      //
-      // Actually perform the task.
-      //
-      try {
-        if (dependencyCycle != null && !handlesDependencyCycles) {
-          throw new InfiniteTaskLoopException(this, dependencyCycle);
-        }
-        internalPerform();
-      } finally {
-        stopwatch.stop();
-      }
-    } on AnalysisException {
-      rethrow;
-    } catch (exception, stackTrace) {
-      throw new AnalysisException(
-          'Unexpected exception while performing $description',
-          new CaughtException(exception, stackTrace));
-    }
-  }
-}
-
-/**
- * A description of a [List]-based analysis result that can be computed by an
- * [AnalysisTask].
- *
- * Clients are not expected to subtype this class.
- */
-abstract class ListResultDescriptor<E> implements ResultDescriptor<List<E>> {
-  /**
-   * Initialize a newly created analysis result to have the given [name] and
-   * [defaultValue]. If a [cachingPolicy] is provided, it will control how long
-   * values associated with this result will remain in the cache.
-   */
-  factory ListResultDescriptor(String name, List<E> defaultValue,
-      {ResultCachingPolicy<List<E>> cachingPolicy}) = ListResultDescriptorImpl<E>;
-
-  @override
-  ListTaskInput<E> of(AnalysisTarget target);
-}
-
-/**
- * A description of an input to an [AnalysisTask] that can be used to compute
- * that input.
- *
- * Clients are not expected to subtype this class.
- */
-abstract class ListTaskInput<E> extends TaskInput<List<E>> {
-  /**
-   * Return a task input that can be used to compute a list whose elements are
-   * the result of passing the elements of this input to the [mapper] function.
-   */
-  ListTaskInput /*<V>*/ toList(UnaryFunction<E, dynamic /*<V>*/ > mapper);
-
-  /**
-   * Return a task input that can be used to compute a list whose elements are
-   * [valueResult]'s associated with those elements.
-   */
-  ListTaskInput /*<V>*/ toListOf(ResultDescriptor /*<V>*/ valueResult);
-
-  /**
-   * Return a task input that can be used to compute a map whose keys are the
-   * elements of this input and whose values are the result of passing the
-   * corresponding key to the [mapper] function.
-   */
-  MapTaskInput<E, dynamic /*V*/ > toMap(
-      UnaryFunction<E, dynamic /*<V>*/ > mapper);
-
-  /**
-   * Return a task input that can be used to compute a map whose keys are the
-   * elements of this input and whose values are the [valueResult]'s associated
-   * with those elements.
-   */
-  MapTaskInput<AnalysisTarget, dynamic /*V*/ > toMapOf(
-      ResultDescriptor /*<V>*/ valueResult);
-}
-
-/**
- * A description of an input with a [Map] based values.
- *
- * Clients are not expected to subtype this class.
- */
-abstract class MapTaskInput<K, V> extends TaskInput<Map<K, V>> {
-  /**
-   * [V] must be a [List].
-   * Return a task input that can be used to compute a list whose elements are
-   * the result of passing keys [K] and the corresponding elements of [V] to
-   * the [mapper] function.
-   */
-  TaskInput<List /*<E>*/ > toFlattenList(
-      BinaryFunction<K, dynamic /*element of V*/, dynamic /*<E>*/ > mapper);
-}
-
-/**
- * A policy object that can compute sizes of results and provide the maximum
- * active and idle sizes that can be kept in the cache.
- *
- * All the [ResultDescriptor]s with the same [ResultCachingPolicy] instance
- * share the same total size in a cache.
- */
-abstract class ResultCachingPolicy<T> {
-  /**
-   * Return the maximum total size of results that can be kept in the cache
-   * while analysis is in progress.
-   */
-  int get maxActiveSize;
-
-  /**
-   * Return the maximum total size of results that can be kept in the cache
-   * while analysis is idle.
-   */
-  int get maxIdleSize;
-
-  /**
-   * Return the size of the given [object].
-   */
-  int measure(T object);
-}
-
-/**
- * A description of an analysis result that can be computed by an [AnalysisTask].
- *
- * Clients are not expected to subtype this class.
- */
-abstract class ResultDescriptor<V> {
-  /**
-   * Initialize a newly created analysis result to have the given [name] and
-   * [defaultValue].
-   *
-   * The given [cachingPolicy] is used to limit the total size of results
-   * described by this descriptor. If no policy is specified, the results are
-   * never evicted from the cache, and removed only when they are invalidated.
-   */
-  factory ResultDescriptor(String name, V defaultValue,
-      {ResultCachingPolicy<V> cachingPolicy}) = ResultDescriptorImpl;
-
-  /**
-   * Return the caching policy for results described by this descriptor.
-   */
-  ResultCachingPolicy<V> get cachingPolicy;
-
-  /**
-   * Return the default value for results described by this descriptor.
-   */
-  V get defaultValue;
-
-  /**
-   * Return the name of this descriptor.
-   */
-  String get name;
-
-  /**
-   * Return a task input that can be used to compute this result for the given
-   * [target].
-   */
-  TaskInput<V> of(AnalysisTarget target);
-}
-
-/**
- * A description of an [AnalysisTask].
- */
-abstract class TaskDescriptor {
-  /**
-   * Initialize a newly created task descriptor to have the given [name] and to
-   * describe a task that takes the inputs built using the given [inputBuilder],
-   * and produces the given [results]. The [buildTask] will be used to create
-   * the instance of [AnalysisTask] thusly described.
-   */
-  factory TaskDescriptor(String name, BuildTask buildTask,
-      CreateTaskInputs inputBuilder,
-      List<ResultDescriptor> results) = TaskDescriptorImpl;
-
-  /**
-   * Return the builder used to build the inputs to the task.
-   */
-  CreateTaskInputs get createTaskInputs;
-
-  /**
-   * Return the name of the task being described.
-   */
-  String get name;
-
-  /**
-   * Return a list of the analysis results that will be computed by this task.
-   */
-  List<ResultDescriptor> get results;
-
-  /**
-   * Create and return a task that is described by this descriptor that can be
-   * used to compute results based on the given [inputs].
-   */
-  AnalysisTask createTask(AnalysisContext context, AnalysisTarget target,
-      Map<String, dynamic> inputs);
-}
-
-/**
- * A description of an input to an [AnalysisTask] that can be used to compute
- * that input.
- *
- * Clients are not expected to subtype this class.
- */
-abstract class TaskInput<V> {
-  /**
-   * Create and return a builder that can be used to build this task input.
-   */
-  TaskInputBuilder<V> createBuilder();
-
-  /**
-   * Return a task input that can be used to compute a list whose elements are
-   * the result of passing the result of this input to the [mapper] function.
-   */
-  ListTaskInput /*<E>*/ mappedToList(List /*<E>*/ mapper(V value));
-}
-
-/**
- * An object used to build the value associated with a single [TaskInput].
- *
- * All builders work by requesting one or more results (each result being
- * associated with a target). The interaction pattern is modeled after the class
- * [Iterator], in which the method [moveNext] is invoked to move from one result
- * request to the next. The getters [currentResult] and [currentTarget] are used
- * to get the result and target of the current request. The value of the result
- * must be supplied using the [currentValue] setter before [moveNext] can be
- * invoked to move to the next request. When [moveNext] returns `false`,
- * indicating that there are no more requests, the method [inputValue] can be
- * used to access the value of the input that was built.
- *
- * Clients are not expected to subtype this class.
- */
-abstract class TaskInputBuilder<V> {
-  /**
-   * Return the result that needs to be computed, or `null` if [moveNext] has
-   * not been invoked or if the last invocation of [moveNext] returned `false`.
-   */
-  ResultDescriptor get currentResult;
-
-  /**
-   * Return the target for which the result needs to be computed, or `null` if
-   * [moveNext] has not been invoked or if the last invocation of [moveNext]
-   * returned `false`.
-   */
-  AnalysisTarget get currentTarget;
-
-  /**
-   * Set the [value] that was computed for the current result.
-   *
-   * Throws a [StateError] if [moveNext] has not been invoked or if the last
-   * invocation of [moveNext] returned `false`.
-   */
-  void set currentValue(Object value);
-
-  /**
-   * Return the [value] that was computed by this builder.
-   *
-   * Throws a [StateError] if [moveNext] has not been invoked or if the last
-   * invocation of [moveNext] returned `true`.
-   *
-   * Returns `null` if no value could be computed due to a circular dependency.
-   */
-  V get inputValue;
-
-  /**
-   * Record that no value is available for the current result, due to a
-   * circular dependency.
-   *
-   * Throws a [StateError] if [moveNext] has not been invoked or if the last
-   * invocation of [moveNext] returned `false`.
-   */
-  void currentValueNotAvailable();
-
-  /**
-   * Move to the next result that needs to be computed in order to build the
-   * inputs for a task. Return `true` if there is another result that needs to
-   * be computed, or `false` if the inputs have been computed.
-   *
-   * It is safe to invoke [moveNext] after it has returned `false`. In this case
-   * [moveNext] has no effect and will again return `false`.
-   *
-   * Throws a [StateError] if the value of the current result has not been
-   * provided using [currentValue].
-   */
-  bool moveNext();
-}