Merge pull request #5730 from dotty-staging/realizability-cleanup-doc

Realizability: fixes and cleanups of docs

Author: Blaisorblade

compiler/src/dotty/tools/dotc/ast/TreeInfo.scala

@@ -400,11 +400,11 @@ trait TypedTreeInfo extends TreeInfo[Type] { self: Trees.Instance[Type] =>
       def isKnownPureOp(sym: Symbol) =
         sym.owner.isPrimitiveValueClass || sym.owner == defn.StringClass
       if (tree.tpe.isInstanceOf[ConstantType] && isKnownPureOp(tree.symbol) // A constant expression with pure arguments is pure.
-          || (fn.symbol.isStable && !fn.symbol.is(Lazy))
+          || (fn.symbol.isStableMember && !fn.symbol.is(Lazy))
           || fn.symbol.isPrimaryConstructor && fn.symbol.owner.isNoInitsClass) // TODO: include in isStable?
         minOf(exprPurity(fn), args.map(exprPurity)) `min` Pure
       else if (fn.symbol.is(Erased)) Pure
-      else if (fn.symbol.isStable /* && fn.symbol.is(Lazy) */)
+      else if (fn.symbol.isStableMember /* && fn.symbol.is(Lazy) */)
         minOf(exprPurity(fn), args.map(exprPurity)) `min` Idempotent
       else Impure
     case Typed(expr, _) =>
@@ -439,7 +439,7 @@ trait TypedTreeInfo extends TreeInfo[Type] { self: Trees.Instance[Type] =>
     val sym = tree.symbol
     if (!tree.hasType) Impure
     else if (!tree.tpe.widen.isParameterless || sym.isEffectivelyErased) SimplyPure
-    else if (!sym.isStable) Impure
+    else if (!sym.isStableMember) Impure
     else if (sym.is(Module))
       if (sym.moduleClass.isNoInitsClass) Pure else Idempotent
     else if (sym.is(Lazy)) Idempotent
@@ -521,7 +521,7 @@ trait TypedTreeInfo extends TreeInfo[Type] { self: Trees.Instance[Type] =>
       case tpe: PolyType => maybeGetterType(tpe.resultType)
       case _ => false
     }
-    sym.owner.isClass && !sym.isStable && maybeGetterType(sym.info)
+    sym.owner.isClass && !sym.isStableMember && maybeGetterType(sym.info)
   }
 
   /** Is tree a reference to a mutable variable, or to a potential getter

compiler/src/dotty/tools/dotc/core/CheckRealizable.scala

@@ -10,7 +10,7 @@ import collection.mutable
 /** Realizability status */
 object CheckRealizable {
 
-  abstract class Realizability(val msg: String) {
+  sealed abstract class Realizability(val msg: String) {
     def andAlso(other: => Realizability): Realizability =
       if (this == Realizable) other else this
     def mapError(f: Realizability => Realizability): Realizability =
@@ -47,10 +47,18 @@ object CheckRealizable {
   def boundsRealizability(tp: Type)(implicit ctx: Context): Realizability =
     new CheckRealizable().boundsRealizability(tp)
 
-  private val LateInitialized = Lazy | Erased,
+  private val LateInitialized = Lazy | Erased
 }
 
-/** Compute realizability status */
+/** Compute realizability status.
+  *
+  * A type T is realizable iff it is inhabited by non-null values. This ensures that its type members have good bounds
+  * (in the sense from DOT papers). A type projection T#L is legal if T is realizable, and can be understood as
+  * Scala 2's `v.L forSome { val v: T }`.
+  *
+  * In general, a realizable type can have multiple inhabitants, hence it need not be stable (in the sense of
+  * Type.isStable).
+  */
 class CheckRealizable(implicit ctx: Context) {
   import CheckRealizable._
 
@@ -66,13 +74,22 @@ class CheckRealizable(implicit ctx: Context) {
 
   /** The realizability status of given type `tp`*/
   def realizability(tp: Type): Realizability = tp.dealias match {
+    /*
+     * A `TermRef` for a path `p` is realizable if
+     * - `p`'s type is stable and realizable, or
+     * - its underlying path is idempotent (that is, *stable*), total, and not null.
+     * We don't check yet the "not null" clause: that will require null-safety checking.
+     *
+     * We assume that stability of tp.prefix is checked elsewhere, since that's necessary for the path to be legal in
+     * the first place.
+     */
     case tp: TermRef =>
       val sym = tp.symbol
       lazy val tpInfoRealizable = realizability(tp.info)
-      if (sym.is(Stable)) realizability(tp.prefix)
+      if (sym.is(StableRealizable)) realizability(tp.prefix)
       else {
         val r =
-          if (sym.isStable && !isLateInitialized(sym))
+          if (sym.isStableMember && !isLateInitialized(sym))
             // it's realizable because we know that a value of type `tp` has been created at run-time
             Realizable
           else if (!sym.isEffectivelyFinal)
@@ -83,10 +100,14 @@ class CheckRealizable(implicit ctx: Context) {
             // roughly: it's realizable if the info does not have bad bounds
             tpInfoRealizable.mapError(r => new ProblemInUnderlying(tp, r))
         r andAlso {
-          if (sym.isStable) sym.setFlag(Stable) // it's known to be stable and realizable
+          if (sym.isStableMember) sym.setFlag(StableRealizable) // it's known to be stable and realizable
           realizability(tp.prefix)
         } mapError { r =>
-          if (tp.info.isStable && tpInfoRealizable == Realizable) Realizable else r
+          // A mutable path is in fact stable and realizable if it has a realizable singleton type.
+          if (tp.info.isStable && tpInfoRealizable == Realizable) {
+            sym.setFlag(StableRealizable)
+            Realizable
+          } else r
         }
       }
     case _: SingletonType | NoPrefix =>

compiler/src/dotty/tools/dotc/core/Flags.scala

@@ -329,7 +329,7 @@ object Flags {
   final val Abstract: FlagSet = commonFlag(23, "abstract")
 
   /** Lazy val or method is known or assumed to be stable and realizable */
-  final val Stable: FlagSet = termFlag(24, "<stable>")
+  final val StableRealizable: FlagSet = termFlag(24, "<stable>")
 
   /** A case parameter accessor */
   final val CaseAccessor: FlagSet = termFlag(25, "<caseaccessor>")
@@ -509,7 +509,7 @@ object Flags {
   final val RetainedTypeArgFlags: FlagSet = VarianceFlags | Protected | Local
 
   /** Modules always have these flags set */
-  final val ModuleValCreationFlags: FlagSet = ModuleVal | Lazy | Final | Stable
+  final val ModuleValCreationFlags: FlagSet = ModuleVal | Lazy | Final | StableRealizable
 
   /** Module classes always have these flags set */
   final val ModuleClassCreationFlags: FlagSet = ModuleClass | Final
@@ -540,7 +540,7 @@ object Flags {
   /** Flags that can apply to a module val */
   final val RetainedModuleValFlags: FlagSet = RetainedModuleValAndClassFlags |
     Override | Final | Method | Implicit | Lazy |
-    Accessor | AbsOverride | Stable | Captured | Synchronized | Erased
+    Accessor | AbsOverride | StableRealizable | Captured | Synchronized | Erased
 
   /** Flags that can apply to a module class */
   final val RetainedModuleClassFlags: FlagSet = RetainedModuleValAndClassFlags |
@@ -585,7 +585,7 @@ object Flags {
   final val InlineOrProxy: FlagSet = Inline | InlineProxy
 
   /** Assumed to be pure */
-  final val StableOrErased: FlagSet = Stable | Erased
+  final val StableOrErased: FlagSet = StableRealizable | Erased
 
   /** Labeled `private`, `final`, or `inline` */
   final val EffectivelyFinal: FlagSet = Private | Final | Inline
@@ -678,7 +678,7 @@ object Flags {
   final val JavaEnumTrait: FlagConjunction = allOf(JavaDefined, Enum)
 
   /** A Java enum value */
-  final val JavaEnumValue: FlagConjunction = allOf(Stable, JavaStatic, JavaDefined, Enum)
+  final val JavaEnumValue: FlagConjunction = allOf(StableRealizable, JavaStatic, JavaDefined, Enum)
 
   /** Labeled private[this] */
   final val PrivateLocal: FlagConjunction = allOf(Private, Local)
@@ -687,7 +687,7 @@ object Flags {
   final val PrivateLocalParamAccessor: FlagConjunction = allOf(Private, Local, ParamAccessor)
 
   /** A parameter forwarder */
-  final val ParamForwarder: FlagConjunction = allOf(Method, Stable, ParamAccessor)
+  final val ParamForwarder: FlagConjunction = allOf(Method, StableRealizable, ParamAccessor)
 
   /** A private[this] parameter */
   final val PrivateLocalParam: FlagConjunction = allOf(Private, Local, Param)

compiler/src/dotty/tools/dotc/core/SymDenotations.scala

@@ -608,10 +608,19 @@ object SymDenotations {
          }
       )
 
-    /** Is this a denotation of a stable term (or an arbitrary type)? */
-    final def isStable(implicit ctx: Context): Boolean = {
+    /** Is this a denotation of a stable term (or an arbitrary type)?
+      * Terms are stable if they are idempotent (as in TreeInfo.Idempotent): that is, they always return the same value,
+      * if any.
+      *
+      * A *member* is stable, basically, if it behaves like a field projection: that is, it projects a constant result
+      * out of its owner.
+      *
+      * However, a stable member might not yet be initialized (if it is an object or anyhow lazy).
+      * So the first call to a stable member might fail and/or produce side effects.
+      */
+    final def isStableMember(implicit ctx: Context): Boolean = {
       def isUnstableValue = is(UnstableValue) || info.isInstanceOf[ExprType]
-      isType || is(Stable) || !isUnstableValue
+      isType || is(StableRealizable) || !isUnstableValue
     }
 
     /** Is this a denotation of a class that does not have - either direct or inherited -

compiler/src/dotty/tools/dotc/core/Types.scala

@@ -147,9 +147,13 @@ object Types {
     /** Is this a value type or a wildcard? */
     final def isValueTypeOrWildcard: Boolean = isValueType || this.isInstanceOf[WildcardType]
 
-    /** Does this type denote a stable reference (i.e. singleton type)? */
+    /** Does this type denote a stable reference (i.e. singleton type)?
+      *
+      * Like in isStableMember, "stability" means idempotence.
+      * Rationale: If an expression has a stable type, the expression must be idempotent, so stable types
+      * must be singleton types of stable expressions. */
     final def isStable(implicit ctx: Context): Boolean = stripTypeVar match {
-      case tp: TermRef => tp.symbol.isStable && tp.prefix.isStable || tp.info.isStable
+      case tp: TermRef => tp.symbol.isStableMember && tp.prefix.isStable || tp.info.isStable
       case _: SingletonType | NoPrefix => true
       case tp: RefinedOrRecType => tp.parent.isStable
       case tp: ExprType => tp.resultType.isStable
@@ -542,7 +546,7 @@ object Types {
         case tp: TermRef =>
           go (tp.underlying match {
             case mt: MethodType
-            if mt.paramInfos.isEmpty && (tp.symbol is Stable) => mt.resultType
+            if mt.paramInfos.isEmpty && (tp.symbol is StableRealizable) => mt.resultType
             case tp1 => tp1
           })
         case tp: TypeRef =>
@@ -1005,7 +1009,7 @@ object Types {
     /** Widen type if it is unstable (i.e. an ExprType, or TermRef to unstable symbol */
     final def widenIfUnstable(implicit ctx: Context): Type = stripTypeVar match {
       case tp: ExprType => tp.resultType.widenIfUnstable
-      case tp: TermRef if !tp.symbol.isStable => tp.underlying.widenIfUnstable
+      case tp: TermRef if !tp.symbol.isStableMember => tp.underlying.widenIfUnstable
       case _ => this
     }
 
@@ -2200,6 +2204,8 @@ object Types {
     def underlyingRef: TermRef
   }
 
+  /** The singleton type for path prefix#myDesignator.
+    */
   abstract case class TermRef(override val prefix: Type,
                               private var myDesignator: Designator)
     extends NamedType with SingletonType with ImplicitRef {

compiler/src/dotty/tools/dotc/core/tasty/TreePickler.scala

@@ -653,7 +653,7 @@ class TreePickler(pickler: TastyPickler) {
       if (flags is Accessor) writeByte(FIELDaccessor)
       if (flags is CaseAccessor) writeByte(CASEaccessor)
       if (flags is DefaultParameterized) writeByte(DEFAULTparameterized)
-      if (flags is Stable) writeByte(STABLE)
+      if (flags is StableRealizable) writeByte(STABLE)
       if (flags is Extension) writeByte(EXTENSION)
       if (flags is ParamAccessor) writeByte(PARAMsetter)
       assert(!(flags is Label))

compiler/src/dotty/tools/dotc/core/tasty/TreeUnpickler.scala

@@ -626,7 +626,7 @@ class TreeUnpickler(reader: TastyReader,
           case CONTRAVARIANT => addFlag(Contravariant)
           case SCALA2X => addFlag(Scala2x)
           case DEFAULTparameterized => addFlag(DefaultParameterized)
-          case STABLE => addFlag(Stable)
+          case STABLE => addFlag(StableRealizable)
           case EXTENSION => addFlag(Extension)
           case PARAMsetter =>
             addFlag(ParamAccessor)

compiler/src/dotty/tools/dotc/core/unpickleScala2/PickleBuffer.scala

@@ -218,7 +218,7 @@ object PickleBuffer {
       LOCAL -> Local,
       JAVA -> JavaDefined,
       SYNTHETIC -> Synthetic,
-      STABLE -> Stable,
+      STABLE -> StableRealizable,
       STATIC -> JavaStatic,
       CASEACCESSOR -> CaseAccessor,
       DEFAULTPARAM -> (DefaultParameterized, Trait),

compiler/src/dotty/tools/dotc/interactive/Completion.scala

@@ -260,7 +260,7 @@ object Completion {
       !sym.is(Artifact) &&
       (
            (mode.is(Mode.Term) && sym.isTerm)
-        || (mode.is(Mode.Type) && (sym.isType || sym.isStable))
+        || (mode.is(Mode.Type) && (sym.isType || sym.isStableMember))
       )
 
     /**

compiler/src/dotty/tools/dotc/parsing/JavaParsers.scala

@@ -858,7 +858,7 @@ object JavaParsers {
           skipAhead()
           accept(RBRACE)
         }
-        ValDef(name.toTermName, enumType, unimplementedExpr).withMods(Modifiers(Flags.JavaEnum | Flags.Stable | Flags.JavaDefined | Flags.JavaStatic))
+        ValDef(name.toTermName, enumType, unimplementedExpr).withMods(Modifiers(Flags.JavaEnum | Flags.StableRealizable | Flags.JavaDefined | Flags.JavaStatic))
       }
     }