Work in progress: front end hot reload API

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';
+
+import 'compiler_options.dart';
+
+/// Represents the difference between "old" and "new" states of a program.
+///
+/// Not intended to be implemented or extended by clients.
+class DeltaProgram {
+  /// The new state of the program.
+  ///
+  /// Libraries whose kernel representation is known to be unchanged since the
+  /// last [DeltaProgram] are not included.
+  final Map<Uri, Program> newState;

[scheglov, 2017/01/16 19:24:58]

Program?
I don't know about Kernel much, but if Program the program is a collection of
libraries, then what is the Uri of an entry in the map?

[Paul Berry, 2017/01/17 13:45:31]

It's a little confusing because we are taking advantage of kernel's modular
compilation features.  The way we're using it, each Program will contain the
complete code for one library, plus just a skeletal representation of all the
libraries that are referenced (kind of like a summary of those libraries, except
smaller, since it only contains things that are referenced).  So the Uri of an
entry in the map tells which library is fully represented in the corresponding
Program object.

+
+  DeltaProgram(this.newState);
+
+  /// TODO(paulberry): add information about libraries that were removed.
+}
+
+/// Interface for generating an initial kernel representation of a program and
+/// keeping it up to date as incremental changes are made.
+///
+/// This class maintains an internal "previous program state"; each
+/// time [computeDelta] is called, it updates the previous program state and
+/// produces a representation of what has changed.  When there are few changes,
+/// a call to [computeDelta] should be much faster than compiling the whole
+/// program from scratch.
+///
+/// This class also maintains a set of "valid sources", which is a (possibly
+/// empty) subset of the sources constituting the previous program state.  Files
+/// in this set are assumed to be unchanged since the last call to
+/// [computeDelta].
+///
+/// Behavior is undefined if the client does not obey the following concurrency
+/// restrictions:
+/// - no two invocations of [computeDelta] may be outstanding at any given time.
+/// - neither [invalidate] nor [invalidateAll] may be called while an invocation
+///   of [computeDelta] is outstanding.
+///
+/// Not intended to be implemented or extended by clients.
+abstract class IncrementalKernelGenerator {
+  /// Creates an [IncrementalKernelGenerator] which is prepared to generate
+  /// kernel representations of the program whose main library is in the given
+  /// [source].
+  ///
+  /// No file system access is performed by this constructor; the initial
+  /// "previous program state" is an empty program containing no code, and the
+  /// initial set of valid sources is empty.  To obtain a kernel representation
+  /// of the program, call [computeDelta].
+  factory IncrementalKernelGenerator(Uri source, CompilerOptions options) =>
+      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 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();
+
+  /// 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();
+}