Polishing some cc classes

Author: odersky

compiler/src/dotty/tools/dotc/cc/CaptureAnnotation.scala

@@ -11,13 +11,23 @@ import config.Printers.capt
 import printing.Printer
 import printing.Texts.Text
 
-
+/** An annotation representing a capture set and whether it is boxed.
+ *  It simulates a normal @retains annotation except that it is more efficient,
+ *  supports variables as capture sets, and adds a `boxed` flag.
+ *  These annotations are created during capture checking. Before that
+ *  there are only regular @retains and @retainsByName annotations.
+ *  @param refs    the capture set
+ *  @param boxed   whether the type carrying the annotation is boxed
+ *  @param cls     the underlying class (either annotation.retains or annotation.retainsByName)
+ */
 case class CaptureAnnotation(refs: CaptureSet, boxed: Boolean)(cls: Symbol) extends Annotation:
   import CaptureAnnotation.*
   import tpd.*
 
+  /** A cache for boxed version of a capturing type with this annotation */
   val boxedType = BoxedTypeCache()
 
+  /** Reconstitute annotation tree from capture set */
   override def tree(using Context) =
     val elems = refs.elems.toList.map {
       case cr: TermRef => ref(cr)
@@ -30,8 +40,7 @@ case class CaptureAnnotation(refs: CaptureSet, boxed: Boolean)(cls: Symbol) exte
   override def symbol(using Context) = cls
 
   override def derivedAnnotation(tree: Tree)(using Context): Annotation =
-    if refs == CaptureSet.universal then this
-    else unsupported("derivedAnnotation(Tree)")
+    unsupported(i"derivedAnnotation(Tree), $tree, $refs")
 
   def derivedAnnotation(refs: CaptureSet, boxed: Boolean)(using Context): Annotation =
     if (this.refs eq refs) && (this.boxed == boxed) then this
@@ -42,9 +51,9 @@ case class CaptureAnnotation(refs: CaptureSet, boxed: Boolean)(cls: Symbol) exte
       this.refs == refs && this.boxed == boxed && this.symbol == that.symbol
     case _ => false
 
-  override def mapWith(tp: TypeMap)(using Context) =
+  override def mapWith(tm: TypeMap)(using Context) =
     val elems = refs.elems.toList
-    val elems1 = elems.mapConserve(tp)
+    val elems1 = elems.mapConserve(tm)
     if elems1 eq elems then this
     else if elems1.forall(_.isInstanceOf[CaptureRef])
     then derivedAnnotation(CaptureSet(elems1.asInstanceOf[List[CaptureRef]]*), boxed)
@@ -66,16 +75,3 @@ case class CaptureAnnotation(refs: CaptureSet, boxed: Boolean)(cls: Symbol) exte
     case _ => false
 
 end CaptureAnnotation
-
-/** A one-element cache for the boxed version of an unboxed capturing type */
-class BoxedTypeCache:
-  private var boxed: Type = compiletime.uninitialized
-  private var unboxed: Type = NoType
-
-  def apply(tp: AnnotatedType)(using Context): Type =
-    if tp ne unboxed then
-      unboxed = tp
-      val CapturingType(parent, refs) = tp: @unchecked
-      boxed = CapturingType(parent, refs, boxed = true)
-    boxed
-end BoxedTypeCache

compiler/src/dotty/tools/dotc/cc/CaptureOps.scala

@@ -13,18 +13,24 @@ import tpd.*
 private val Captures: Key[CaptureSet] = Key()
 private val BoxedType: Key[BoxedTypeCache] = Key()
 
-def retainedElems(tree: Tree)(using Context): List[Tree] = tree match
+/** The arguments of a @retains or @retainsByName annotation */
+private[cc] def retainedElems(tree: Tree)(using Context): List[Tree] = tree match
   case Apply(_, Typed(SeqLiteral(elems, _), _) :: Nil) => elems
   case _ => Nil
 
+/** An exception thrown if a @retains argument is not syntactically a CaptureRef */
 class IllegalCaptureRef(tpe: Type) extends Exception
 
 extension (tree: Tree)
 
+  /** Map tree with CaptureRef type to its type, throw IllegalCaptureRef otherwise */
   def toCaptureRef(using Context): CaptureRef = tree.tpe match
     case ref: CaptureRef => ref
     case tpe => throw IllegalCaptureRef(tpe)
 
+  /** Convert a @retains or @retainsByName annotation tree to the capture set it represents.
+   *  For efficience, the result is cached as an Attachment on the tree.
+   */
   def toCaptureSet(using Context): CaptureSet =
     tree.getAttachment(Captures) match
       case Some(refs) => refs
@@ -36,11 +42,16 @@ extension (tree: Tree)
 
 extension (tp: Type)
 
+  /** @pre `tp` is a CapturingType */
   def derivedCapturingType(parent: Type, refs: CaptureSet)(using Context): Type = tp match
     case tp @ CapturingType(p, r) =>
       if (parent eq p) && (refs eq r) then tp
       else CapturingType(parent, refs, tp.isBoxed)
 
+  /** If this is a unboxed capturing type with nonempty capture set, its boxed version.
+   *  Or, if type is a TypeBounds of capturing types, the version where the bounds are boxed.
+   *  The identity for all other types.
+   */
   def boxed(using Context): Type = tp.dealias match
     case tp @ CapturingType(parent, refs) if !tp.isBoxed && !refs.isAlwaysEmpty =>
       tp.annot match
@@ -56,12 +67,16 @@ extension (tp: Type)
     case _ =>
       tp
 
+  /** The boxed version of `tp`, unless `tycon` is a function symbol */
   def boxedUnlessFun(tycon: Type)(using Context) =
-    if ctx.phase != Phases.checkCapturesPhase || defn.isFunctionClass(tycon.typeSymbol)
+    if ctx.phase != Phases.checkCapturesPhase || defn.isFunctionSymbol(tycon.typeSymbol)
     then tp
     else tp.boxed
 
-  /** The boxed capture set of a type */
+  /** The capture set of `tp` consisting of all top-level captures under a box.
+   *  Unlike for `boxed` this also considers parents of capture types, unions and
+   *  intersections, and type proxies other than abstract types.
+   */
   def boxedCaptureSet(using Context): CaptureSet =
     def getBoxed(tp: Type): CaptureSet = tp match
       case tp @ CapturingType(parent, refs) =>

compiler/src/dotty/tools/dotc/cc/CapturingType.scala

@@ -5,20 +5,41 @@ package cc
 import core.*
 import Types.*, Symbols.*, Contexts.*
 
-/** A capturing type. This is internally represented as an annotated type with a `retains`
- *  annotation, but the extractor will succeed only at phase CheckCaptures.
+/** A (possibly boxed) capturing type. This is internally represented as an annotated type with a @retains
+ *  or @retainsByName annotation, but the extractor will succeed only at phase CheckCaptures.
+ *  That way, we can ignore caturing information until phase CheckCaptures since it is
+ *  wrapped in a plain annotation.
+ *
+ *  The same trick does not work for the boxing information. Boxing is context dependent, so
+ *  we have to add that information in the Setup step preceding CheckCaptures. Boxes are
+ *  added for all type arguments of methods. For type arguments of applied types a different
+ *  strategy is used where we box arguments of applied types that are not functions when
+ *  accessing the argument.
+ *
+ *  An alternative strategy would add boxes also to arguments of applied types during setup.
+ *  But this would have to be done for all possibly accessibly types from the compiled units
+ *  as well as their dependencies. It's difficult to do this in a DenotationTransformer without
+ *  accidentally forcing symbol infos. That's why this alternative was not implemented.
+ *  If we would go back on this it would make sense to also treat captuyring types different
+ *  from annotations and to generate them all during Setup and in DenotationTransformers.
  */
 object CapturingType:
 
+  /** Smart constructor that drops empty capture sets and fuses compatible capturiong types.
+   *  An outer type capturing type A can be fused with an inner capturing type B if their
+   *  boxing status is the same or if A is boxed.
+   */
   def apply(parent: Type, refs: CaptureSet, boxed: Boolean = false)(using Context): Type =
     if refs.isAlwaysEmpty then parent
     else parent match
       case parent @ CapturingType(parent1, refs1) if boxed || !parent.isBoxed =>
-        // Fuse types except if nested type is boxed and current one isn't.
         apply(parent1, refs ++ refs1, boxed)
       case _ =>
         AnnotatedType(parent, CaptureAnnotation(refs, boxed)(defn.RetainsAnnot))
 
+  /** An extractor that succeeds only during CheckCapturingPhase. Boxing statis is
+   *  returned separately by CaptureOps.isBoxed.
+   */
   def unapply(tp: AnnotatedType)(using Context): Option[(Type, CaptureSet)] =
     if ctx.phase == Phases.checkCapturesPhase && tp.annot.symbol == defn.RetainsAnnot then
       EventuallyCapturingType.unapply(tp)

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

@@ -36,7 +36,7 @@ import config.Printers.{core, typr, matchTypes}
 import reporting.{trace, Message}
 import java.lang.ref.WeakReference
 import compiletime.uninitialized
-import cc.{CapturingType, CaptureSet, derivedCapturingType, retainedElems, isBoxedCapturing, EventuallyCapturingType, boxedUnlessFun}
+import cc.{CapturingType, CaptureSet, derivedCapturingType, isBoxedCapturing, EventuallyCapturingType, boxedUnlessFun}
 import CaptureSet.{CompareResult, IdempotentCaptRefMap, IdentityCaptRefMap}
 
 import scala.annotation.internal.sharable

tests/run-custom-args/tasty-inspector/stdlibExperimentalDefinitions.scala

@@ -50,8 +50,8 @@ val experimentalDefinitionInLibrary = Set(
   "scala.annotation.capability",
   "scala.annotation.internal.CaptureChecked",
   "scala.annotation.internal.requiresCapability",
-  "scala.retains",
-  "scala.retainsByName",
+  "scala.annotation.retains",
+  "scala.annotation.retainsByName",
 
   //// New APIs: Mirror
   // Can be stabilized in 3.3.0 or later.