Add ClosureRepresentationInfo, the new public face of ClosureClassMap

pkg/compiler/lib/src/closure.dart

 // Copyright (c) 2012, 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 closureToClassMapper;
 
 import 'common/names.dart' show Identifiers;
 import 'common/resolution.dart' show ParsingContext, Resolution;
 import 'common/tasks.dart' show CompilerTask;
 import 'common.dart';
 import 'compiler.dart' show Compiler;
 import 'constants/expressions.dart';
 import 'elements/elements.dart';
 import 'elements/entities.dart';
 import 'elements/entity_utils.dart' as utils;
 import 'elements/modelx.dart'
     show BaseFunctionElementX, ClassElementX, ElementX;
 import 'elements/resolution_types.dart';
 import 'elements/types.dart';
 import 'elements/visitor.dart' show ElementVisitor;
 import 'js_backend/js_backend.dart' show JavaScriptBackend;
 import 'resolution/tree_elements.dart' show TreeElements;
 import 'package:front_end/src/fasta/scanner.dart' show Token;
 import 'tree/tree.dart';
 import 'util/util.dart';
 import 'world.dart' show ClosedWorldRefiner;
 
 /// Where T is ir.Node or Node.
+// TODO(efortuna): Rename this class.
 abstract class ClosureClassMaps<T> {
   ClosureClassMap getMemberMap(MemberEntity member);

[Johnni Winther, 2017/06/14 09:22:30]

Do we still need these?

[Emily Fortuna, 2017/06/15 00:11:21]

no, but I was going to delete them in a follow-up CL.

but I went ahead and did it here.

   ClosureClassMap getLocalFunctionMap(Local localFunction);
 
+  /// Look up information about the variables that have been mutated and are
+  /// used inside the scope of [node].
+  ClosureRepresentationInfo getClosureRepresentationInfo(Entity member);

[Johnni Winther, 2017/06/14 09:22:30]

Add a TODO for me to split this into members and local functions (like
getMemberMap/getLocalFunctionMap)

[Emily Fortuna, 2017/06/15 00:11:21]

Done.

+
   /// Look up information about a loop, in case any variables it declares need
   /// to be boxed/snapshotted.
   LoopClosureRepresentationInfo getClosureRepresentationInfoForLoop(T loopNode);
 
   /// Accessor to the information about closures that the SSA builder will use.
   ClosureAnalysisInfo getClosureAnalysisInfo(T node);
 }
 
 /// Class that provides a black-box interface to information gleaned from
 /// analyzing a closure's characteristics, most commonly used to influence how
@@ skipping 26 matching lines @@
 }
 
 /// Class that describes the actual mechanics of how a loop is
 /// converted/rewritten without closures. Unlike JS, the value of a declared
 /// loop iteration variable in any closure is captured/snapshotted inside at
 /// each iteration point, as if we created a new local variable for that value
 /// inside the loop. For example, for the following loop:
 ///
 ///     var lst = [];
 ///     for (int i = 0; i < 5; i++) lst.add(()=>i);
+///     var result = list.map((f) => f()).toList();
 ///
-/// The result of `lst` will be [0, 1, 2, 3, 4], whereas were this JS code
+/// `result` will be [0, 1, 2, 3, 4], whereas were this JS code
 /// the result would be [5, 5, 5, 5, 5]. Because of this difference we need to
 /// create a closure for these sorts of loops to capture the variable's value at
 /// each iteration, by boxing the iteration variable[s].
 class LoopClosureRepresentationInfo extends ClosureAnalysisInfo {
   const LoopClosureRepresentationInfo();
 
   /// True if this loop declares any variables that need to be boxed.
   bool get hasBoxedVariables => false;
 
   /// The set of iteration variables (or variables declared in the for loop
   /// expression (`for (...here...)`) that need to be boxed to snapshot their
   /// value.
   List<Local> get boxedVariables => const <Local>[];
 }
 
+/// Class that describes the actual mechanics of how the converted, rewritten
+/// closure is implemented. For example, for the following closure (named foo
+/// for convenience):
+///
+///   var foo = (x) => y + x;
+///
+/// We would produce the following class to control access to these variables in
+/// the following way (modulo naming of variables, assuming that y is modified
+/// elsewhere in its scope):
+///
+///    class FooClosure {
+///       int y;
+///       FooClosure(this.y);
+///       call(x) => this.y + x;
+///    }
+///
+///  and then to execute this closure, for example:
+///
+///     var foo = new FooClosure(1);
+///     foo.call(2);
+///
+/// if y is modified elsewhere within its scope, accesses to y anywhere in the
+/// code will be controlled via a box object.
+/// I expect this interface to get simpler in subsequent refactorings.

[Johnni Winther, 2017/06/14 09:22:30]

Maybe turn the last line into a TODO?

[Emily Fortuna, 2017/06/15 00:11:21]

Done.

+class ClosureRepresentationInfo {
+  const ClosureRepresentationInfo();
+
+  /// The original local function before any translation.
+  ///
+  /// Will be null for methods.
+  Local get closureEntity => null;
+
+  /// Closures are rewritten in the form of classes that

[Johnni Winther, 2017/06/14 09:22:30]

Weird line break

[Emily Fortuna, 2017/06/15 00:11:21]

Done.

+  /// have fields to control the redirection and editing of variables that are
+  /// "captured" inside a scope (declared in an outer scope but used in an
+  /// inside scope). So this returns the class entity that represents this
+  /// particular rewritten closure.
+  ClassEntity get closureClassEntity => null;
+
+  /// The function that implements the [local] function as a `call` method on
+  /// the closure class.
+  FunctionEntity get callEntity => null;

[Johnni Winther, 2017/06/14 09:22:30]

Maybe rename to [callMethod]?

[Emily Fortuna, 2017/06/15 00:11:21]

Done.

+
+  /// As shown in the example in the comments at the top of this class, we
+  /// create fields in the closure class for each captured variable. This is an
+  /// accessor to that set of fields.
+  List<Local> get createdFieldEntities => const <Local>[];
+
+  /// Convenience reference pointer to the element representing `this`.
+  /// It is only set for instance-members.
+  Local get thisLocal => null;
+
+  /// Convenience pointer to the field entity representation in the closure
+  /// class of the element representing `this`.
+  FieldEntity get thisFieldEntity => null;
+
+  /// Returns true if this [variable] is used inside a `try` block or a `sync*`
+  /// generator (this is important to know because boxing/redirection needs to
+  /// happen for those local variables).
+  ///
+  /// Variables that are used in a try must be treated as boxed because the
+  /// control flow can be non-linear.
+  ///
+  /// Also parameters to a `sync*` generator must be boxed, because of the way
+  /// we rewrite sync* functions. See also comments in
+  /// [ClosureClassMap.useLocal].
+  bool variableIsUsedInTryOrSync(Local variable) => false;
+
+  /// Loop through every variable that has been captured in this closure. This
+  /// consists of all the free variables (variables captured *just* in this
+  /// closure) and all variables captured in nested scopes that we may be
+  /// capturing as well. These nested scopes hold "boxes" to hold the executable
+  /// context for that scope.
+  void forEachCapturedVariable(f(Local from, FieldEntity to)) {}
+
+  /// Loop through each variable that has been boxed in this closure class. Only
+  /// captured variables that are mutated need to be "boxed" (which basically
+  /// puts a thin layer between updates and reads to this variable to ensure
+  /// that every place that accesses it gets the correct updated value).
+  void forEachBoxedVariable(f(Local local, FieldEntity field)) {}
+
+  void forEachFreeVariable(f(Local variable, FieldEntity field)) {}

[Johnni Winther, 2017/06/14 09:22:30]

Add docs

[Emily Fortuna, 2017/06/15 00:11:21]

Done.

+
+  /// Return true if [variable] has been captured and mutated (other variables

[Johnni Winther, 2017/06/14 09:22:30]

(...) -> , if not [variable] doesn't need boxing.

+  /// not require boxing).
+  bool isVariableBoxed(Local variable) => false;
+
+  // TODO(efortuna): Remove this method. The old system was using
+  // ClosureClassMaps for situations other than closure class maps, and that's
+  // just confusing.
+  bool get isClosure => false;
+}
+
 class ClosureTask extends CompilerTask implements ClosureClassMaps<Node> {
   Map<Node, ClosureScope> _closureInfoMap = <Node, ClosureScope>{};
   Map<Element, ClosureClassMap> _closureMappingCache =
       <Element, ClosureClassMap>{};
   Compiler compiler;
   ClosureTask(Compiler compiler)
       : compiler = compiler,
         super(compiler.measurer);
 
   String get name => "Closure Simplifier";
 
   DiagnosticReporter get reporter => compiler.reporter;
 
   ClosureAnalysisInfo getClosureAnalysisInfo(Node node) {
     var value = _closureInfoMap[node];
     return value == null ? const ClosureAnalysisInfo() : value;
   }
 
+  ClosureRepresentationInfo getClosureRepresentationInfo(Element member) {
+    return getClosureToClassMapping(member);
+  }
+
   LoopClosureRepresentationInfo getClosureRepresentationInfoForLoop(
       Node loopNode) {
     var value = _closureInfoMap[loopNode];
     return value == null ? const LoopClosureRepresentationInfo() : value;
   }
 
   ClosureClassMap getMemberMap(MemberElement member) {
     return getClosureToClassMapping(member);
   }
 
@@ skipping 406 matching lines @@
     }
     if (capturedVariables.isNotEmpty) {
       sb.write(separator);
       sb.write('capturedVariables=$capturedVariables');
     }
     sb.write(')');
     return sb.toString();
   }
 }
 
-class ClosureClassMap {
+class ClosureClassMap implements ClosureRepresentationInfo {
   /// The local function element before any translation.
   ///
   /// Will be null for methods.
-  final LocalFunctionElement closureElement;
+  final LocalFunctionElement closureEntity;
 
-  /// The synthesized closure class for [closureElement].
+  /// The synthesized closure class for [closureEntity].
   ///
-  /// The closureClassElement will be null for methods that are not local
+  /// The closureClassEntity will be null for methods that are not local
   /// closures.
-  final ClosureClassElement closureClassElement;
+  final ClosureClassElement closureClassEntity;
 
-  /// The synthesized `call` method of the [ closureClassElement].
+  /// The synthesized `call` method of the [closureClassEntity].
   ///
-  /// The callElement will be null for methods that are not local closures.
-  final MethodElement callElement;
+  /// The callEntity will be null for methods that are not local closures.
+  final MethodElement callEntity;
 
-  /// The [thisElement] makes handling 'this' easier by treating it like any
+  /// The [thisLocal] makes handling 'this' easier by treating it like any
   /// other argument. It is only set for instance-members.
   final ThisLocal thisLocal;
 
   /// Maps free locals, arguments, function elements, and box locals to
   /// their locations.
   final Map<Local, FieldEntity> freeVariableMap = new Map<Local, FieldEntity>();
 
   /// Maps [Loop] and [FunctionExpression] nodes to their [ClosureScope] which
   /// contains their box and the captured variables that are stored in the box.
   /// This map will be empty if the method/closure of this [ClosureData] does
   /// not contain any nested closure.
   final Map<Node, ClosureScope> capturingScopes = new Map<Node, ClosureScope>();
 
   /// Variables that are used in a try must be treated as boxed because the
   /// control flow can be non-linear.
   ///
   /// Also parameters to a `sync*` generator must be boxed, because of the way
   /// we rewrite sync* functions. See also comments in [useLocal].
   // TODO(johnniwinther): Add variables to this only if the variable is mutated.
   final Set<Local> variablesUsedInTryOrGenerator = new Set<Local>();
 
-  ClosureClassMap(this.closureElement, this.closureClassElement,
-      this.callElement, this.thisLocal);
+  ClosureClassMap(this.closureEntity, this.closureClassEntity, this.callEntity,
+      this.thisLocal);
+
+  List<Local> get createdFieldEntities {
+    List<Local> fields = <Local>[];
+    if (closureClassEntity == null) return const <Local>[];
+    closureClassEntity.closureFields.forEach((field) {
+      fields.add(field.local);
+    });
+    return fields;
+  }
 
   void addFreeVariable(Local element) {
     assert(freeVariableMap[element] == null);
     freeVariableMap[element] = null;
   }
 
   Iterable<Local> get freeVariables => freeVariableMap.keys;
 
   bool isFreeVariable(Local element) {
     return freeVariableMap.containsKey(element);
   }
 
   void forEachFreeVariable(f(Local variable, FieldEntity field)) {
     freeVariableMap.forEach(f);
   }
 
-  bool isVariableUsedInTryOrSync(Local variable) =>
+  FieldEntity get thisFieldEntity => freeVariableMap[thisLocal];
+
+  bool variableIsUsedInTryOrSync(Local variable) =>
       variablesUsedInTryOrGenerator.contains(variable);
 
   Local getLocalVariableForClosureField(ClosureFieldElement field) {
     return field.local;
   }
 
-  bool get isClosure => closureElement != null;
+  bool get isClosure => closureEntity != null;
 
   bool capturingScopesBox(Local variable) {
     return capturingScopes.values.any((scope) {
       return scope.boxedLoopVariables.contains(variable);
     });
   }
 
   bool isVariableBoxed(Local variable) {
     FieldEntity copy = freeVariableMap[variable];
     if (copy is BoxFieldElement) {
@@ skipping 156 matching lines @@
         if (boxFieldElement == null) {
           assert(fromElement is! BoxLocal);
           // The variable has not been boxed.
           fieldCaptures.add(fromElement);
         } else {
           // A boxed element.
           data.freeVariableMap[fromElement] = boxFieldElement;
           boxes.add(boxFieldElement.box);
         }
       });
-      ClosureClassElement closureClass = data.closureClassElement;
+      ClosureClassElement closureClass = data.closureClassEntity;
       assert(closureClass != null || (fieldCaptures.isEmpty && boxes.isEmpty));
 
       void addClosureField(Local local, String name) {
         ClosureFieldElement closureField =
             new ClosureFieldElement(name, local, closureClass);
         closureClass.addField(closureField, reporter);
         data.freeVariableMap[local] = closureField;
       }
 
       // Add the box elements first so we get the same ordering.
@@ skipping 35 matching lines @@
           variable.executableContext == executableContext;
     }
 
     if (insideClosure && !inCurrentContext(variable)) {
       closureData.addFreeVariable(variable);
     } else if (inTryStatement) {
       // Don't mark the this-element or a self-reference. This would complicate
       // things in the builder.
       // Note that nested (named) functions are immutable.
       if (variable != closureData.thisLocal &&
-          variable != closureData.closureElement &&
+          variable != closureData.closureEntity &&
           variable is! TypeVariableLocal) {
         closureData.variablesUsedInTryOrGenerator.add(variable);
       }
     } else if (variable is LocalParameterElement &&
         variable.functionDeclaration.asyncMarker == AsyncMarker.SYNC_STAR) {
       // Parameters in a sync* function are shared between each Iterator created
       // by the Iterable returned by the function, therefore they must be boxed.
       closureData.variablesUsedInTryOrGenerator.add(variable);
     }
   }
@@ skipping 366 matching lines @@
         thisElement = new ThisLocal(member);
       }
       closureData = new ClosureClassMap(null, null, null, thisElement);
       if (element is MethodElement) {
         needsRti = compiler.options.enableTypeAssertions ||
             compiler.backend.rtiNeed.methodNeedsRti(element);
       }
     }
     closureMappingCache[element] = closureData;
     closureMappingCache[element.declaration] = closureData;
-    if (closureData.callElement != null) {
-      closureMappingCache[closureData.callElement] = closureData;
+    if (closureData.callEntity != null) {
+      closureMappingCache[closureData.callEntity] = closureData;
     }
 
     inNewScope(node, () {
       // If the method needs RTI, or checked mode is set, we need to
       // escape the potential type variables used in that closure.
       if (needsRti) {
         analyzeTypeVariables(element.type);
       }
 
       visitChildren();
@@ skipping 99 matching lines @@
 ///
 /// Move the below classes to a JS model eventually.
 ///
 abstract class JSEntity implements MemberEntity {
   Local get declaredEntity;
 }
 
 abstract class PrivatelyNamedJSEntity implements JSEntity {
   Entity get rootOfScope;
 }