IncrementalKernalGenerator watch source callback

pkg/front_end/lib/incremental_kernel_generator.dart

 // Copyright (c) 2017, 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.
 
 import 'dart:async';
 
 import 'package:front_end/src/base/processed_options.dart';
 import 'package:front_end/src/incremental_kernel_generator_impl.dart';
 import 'package:kernel/kernel.dart';
 
@@ skipping 48 matching lines @@
       new IncrementalKernelGeneratorImpl(source, new ProcessedOptions(options));
 
   /// Generates a kernel representation of the changes to the program, assuming
   /// that all valid sources are unchanged since the last call to
   /// [computeDelta].
   ///
   /// Source files in the set of valid sources are guaranteed not to be re-read
   /// from disk; they are assumed to be unchanged regardless of the state of the
   /// filesystem.
   ///
+  /// If [watch] is not `null`, then when a source file is first used
+  /// by [computeDelta], [watch] is called with the Uri of that source
+  /// file and `used` == `true` indicating that the source file is being
+  /// used when compiling the program. If during a subsequent call to

[Paul Berry, 2017/01/25 22:03:33]

Please add a sentence explaining that the file contents won't be read until the
future returned by [watch] completes.  (This is necessary to avoid race
conditions, because we need to make sure the client has actually started
watching the file before we read it).

[danrubel, 2017/01/25 22:40:41]

Done.

+  /// [computeDelta], a source file that was being used is no longer used,
+  /// then [watch] is called with the Uri of that source file and
+  /// `used` == `false` indicating that the source file is no longer needed.
+  ///

[Paul Berry, 2017/01/25 22:03:34]

Please add a sentence explaining that multiple invocations of [watch] may be
running concurrently.  (This prevents [watch] from becoming a concurrency
bottleneck).

[danrubel, 2017/01/25 22:40:41]

Done.

   /// If the future completes successfully, the previous file state is updated
   /// and the set of valid sources is set to the set of all sources in the
   /// program.
   ///
   /// If the future completes with an error (due to errors in the compiled
   /// source code), the caller may consider the previous file state and the set
   /// of valid sources to be unchanged; this means that once the user fixes the
   /// errors, it is safe to call [computeDelta] again.
-  Future<DeltaProgram> computeDelta();
+  Future<DeltaProgram> computeDelta({Future<Null> watch(Uri uri, bool used)});
 
   /// Remove any source file(s) associated with the given file path from the set
   /// of valid sources.  This guarantees that those files will be re-read on the
   /// next call to [computeDelta]).
   void invalidate(String path);
 
   /// Remove all source files from the set of valid sources.  This guarantees
   /// that all files will be re-read on the next call to [computeDelta].
   ///
   /// Note that this does not erase the previous program state; the next time
   /// [computeDelta] is called, if parts of the program are discovered to be
   /// unchanged, parts of the previous program state will still be re-used to
   /// speed up compilation.
   void invalidateAll();
 }