IncrementalKernalGenerator watch source callback

pkg/front_end/lib/incremental_kernel_generator.dart

Index: pkg/front_end/lib/incremental_kernel_generator.dart
diff --git a/pkg/front_end/lib/incremental_kernel_generator.dart b/pkg/front_end/lib/incremental_kernel_generator.dart
index 5e809607c8db5e569a55410b395b439764042aca..f5d60a6fcb727439ced18c612bc46bf9e896ef95 100644
--- a/pkg/front_end/lib/incremental_kernel_generator.dart
+++ b/pkg/front_end/lib/incremental_kernel_generator.dart
@@ -66,6 +66,14 @@ abstract class IncrementalKernelGenerator {
   /// 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.
@@ -74,7 +82,7 @@ abstract class IncrementalKernelGenerator {
   /// 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