Add AnalysisContext.onResultInvalidated(descriptor).

pkg/analyzer/lib/src/generated/engine.dart

 // Copyright (c) 2014, 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.src.generated.engine;
 
 import 'dart:async';
 import 'dart:collection';
 
 import 'package:analyzer/dart/ast/ast.dart';
@@ skipping 502 matching lines @@
    */
   bool isServerLibrary(Source librarySource);
 
   /**
    * Return the stream that is notified when a new value for the given
    * [descriptor] is computed.
    */
   Stream<ComputedResult> onResultComputed(ResultDescriptor descriptor);
 
   /**
+   * Return the stream that is notified when a result with the given
+   * [descriptor] is invalidated.
+   */
+  Stream<InvalidatedResultEvent> onResultInvalidated(
+      ResultDescriptor descriptor);
+
+  /**
    * Parse the content of the given [source] to produce an AST structure. The
    * resulting AST structure may or may not be resolved, and may have a slightly
    * different structure depending upon whether it is resolved.
    *
    * Throws an [AnalysisException] if the analysis could not be performed
    *
    * <b>Note:</b> This method cannot be used in an async environment.
    */
   CompilationUnit parseCompilationUnit(Source source);
 
@@ skipping 1325 matching lines @@
   final AnalysisTarget target;
 
   /**
    * The computed value.
    */
   final V value;
 
   ComputedResult(this.context, this.descriptor, this.target, this.value);
 
   @override
-  String toString() => '$descriptor of $target in $context';
+  String toString() => 'Computed $descriptor of $target in $context';
 }
 
 /**
  * An event indicating when a source either starts or stops being implicitly
  * analyzed.
  */
 class ImplicitAnalysisEvent {
   /**
    * The source whose status has changed.
    */
@@ skipping 173 matching lines @@
    */
   void test_flushAstStructures(Source source);
 
   /**
    * Visit all entries of the content cache.
    */
   void visitContentCache(ContentCacheVisitor visitor);
 }
 
 /**
+ * [InvalidatedResultEvent] describes an invalidated analysis result.
+ */
+class InvalidatedResultEvent<V> {

[Brian Wilkerson, 2016/03/08 18:36:36]

Given that it's now identical to ComputedResult (except for toString), I have to
wonder whether there's any value in adding a new class.

I'd recommend generalizing this:
- rename this class to ResultChange (or ResultChangedEvent),
- rename the method to onResultChanged, and
- add two getters wasComputed and wasInvalidated (with a private field).

It would be a breaking change to remove ComputedResult, but we could deprecate
both it and onResultComputed.

+  /**
+   * The context in which the result was invalidated.
+   */
+  final AnalysisContext context;
+
+  /**
+   * The target for which the result was invalidated.
+   */
+  final AnalysisTarget target;
+
+  /**
+   * The descriptor of the result which was invalidated.
+   */
+  final ResultDescriptor<V> descriptor;
+
+  /**
+   * The value of the result before it was invalidated, may be the default
+   * value if the result was flushed.
+   */
+  final V value;
+
+  InvalidatedResultEvent(
+      this.context, this.target, this.descriptor, this.value);
+
+  @override
+  String toString() => 'Invalidated $descriptor of $target';
+}
+
+/**
  * An object that can be used to receive information about errors within the
  * analysis engine. Implementations usually write this information to a file,
  * but can also record the information for later use (such as during testing) or
  * even ignore the information.
  */
 abstract class Logger {
   /**
    * A logger that ignores all logging.
    */
   static final Logger NULL = new NullLogger();
@@ skipping 407 matching lines @@
    * The data that was created from the source.
    */
   final E data;
 
   /**
    * Initialize a newly created holder to associate the given [data] with the
    * given [modificationTime].
    */
   TimestampedData(this.modificationTime, this.data);
 }