Extension point for WorkManagerFactory(s).

pkg/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/error.dart' show AnalysisError;
 import 'package:analyzer/src/generated/java_engine.dart';
 import 'package:analyzer/src/generated/source.dart';
+import 'package:analyzer/src/generated/utilities_general.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
@@ skipping 361 matching lines @@
   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 specification of the given [result] for the given [target].

[Brian Wilkerson, 2015/08/26 16:19:32]

We should probably include the boilerplate for "clients are not expected to
subtype this class".

+ */
+class TargetedResult {
+  /**
+   * An empty list of results.
+   */
+  static final List<TargetedResult> EMPTY_LIST = const <TargetedResult>[];
+
+  /**
+   * The target with which the result is associated.
+   */
+  final AnalysisTarget target;
+
+  /**
+   * The result associated with the target.
+   */
+  final ResultDescriptor result;
+
+  /**
+   * Initialize a new targeted result.
+   */
+  TargetedResult(this.target, this.result);
+
+  @override
+  int get hashCode {
+    return JenkinsSmiHash.combine(target.hashCode, result.hashCode);
+  }
+
+  @override
+  bool operator ==(other) {
+    return other is TargetedResult &&
+        other.target == target &&
+        other.result == result;
+  }
+
+  @override
+  String toString() => '$result for $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,
@@ skipping 104 matching lines @@
    * 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();
 }
+
+/**
+ * [WorkManager]s are used to drive analysis.
+ *
+ * They know specific of the targets and results they care about,
+ * so they can request analysis results in optimal order.

[Brian Wilkerson, 2015/08/26 16:19:32]

We should also have boilerplate here saying "only implement" this class.

+ */
+abstract class WorkManager {
+  /**
+   * Notifies the manager about changes in the explicit source list.
+   */
+  void applyChange(List<Source> addedSources, List<Source> changedSources,
+      List<Source> removedSources);
+
+  /**
+   * Notifies the managers that the given set of priority [targets] was set.
+   */
+  void applyPriorityTargets(List<AnalysisTarget> targets);
+
+  /**
+   * Return a list of all of the errors associated with the given [source].
+   * The list of errors will be empty if the source is not known to the context
+   * or if there are no errors in the source. The errors contained in the list
+   * can be incomplete.
+   */
+  List<AnalysisError> getErrors(Source source);
+
+  /**
+   * Return the next [TargetedResult] that this work manager wants to be
+   * computed, or `null` if this manager doesn't need any new results.
+   */
+  TargetedResult getNextResult();
+
+  /**
+   * Return the priority if the next work order this work manager want to be
+   * computed. The [AnalysisDriver] will perform the work order with
+   * the highest priority.
+   *
+   * Even if the returned value is [WorkOrderPriority.NONE], it still does not
+   * guarantee that [getNextResult] will return not `null`.
+   */
+  WorkOrderPriority getNextResultPriority();
+
+  /**
+   * Notifies the manager about analysis options changes.
+   */
+  void onAnalysisOptionsChanged();
+
+  /**
+   * Notifies the manager about [SourceFactory] changes.
+   */
+  void onSourceFactoryChanged();
+
+  /**
+   * Notifies the manager that the given [outputs] were produced for
+   * the given [target].
+   */
+  void resultsComputed(
+      AnalysisTarget target, Map<ResultDescriptor, dynamic> outputs);
+}
+
+/**
+ * The priorities of work orders returned by [WorkManager]s.

[Brian Wilkerson, 2015/08/26 16:19:32]

Should we have a disclaimer about clients needing to tolerate additions to the
priorities so that we can change it without it being a breaking change, or are
we confident that the current list of priorities is sufficient?

+ */
+enum WorkOrderPriority {
+  /**
+   * Responding to an user's action.
+   */
+  INTERACTIVE,
+
+  /**
+   * Computing information for priority sources.
+   */
+  PRIORITY,
+
+  /**
+   * A work should be done, but without any special urgency.
+   */
+  NORMAL,
+
+  /**
+   * Nothing to do.
+   */
+  NONE
+}