Add caps.freeze wrapper

Author: Linyxus

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

@@ -398,6 +398,7 @@ extension (tp: Type)
   def derivesFromStateful(using Context): Boolean = derivesFromCapTrait(defn.Caps_Stateful)
   def derivesFromShared(using Context): Boolean = derivesFromCapTrait(defn.Caps_SharedCapability)
   def derivesFromUnscoped(using Context): Boolean = derivesFromCapTrait(defn.Caps_Unscoped)
+  def derivesFromMutable(using Context): Boolean = derivesFromCapTrait(defn.Caps_Mutable)
 
   /** Drop @retains annotations everywhere */
   def dropAllRetains(using Context): Type = // TODO we should drop retains from inferred types before unpickling

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

@@ -790,22 +790,44 @@ class CheckCaptures extends Recheck, SymTransformer:
           selType
     }//.showing(i"recheck sel $tree, $qualType = $result")
 
-    /** Recheck applications, with special handling of unsafeAssumePure.
+    /** Recheck `caps.unsafe.unsafeAssumePure(...)` */
+    def applyAssumePure(tree: Apply, pt: Type)(using Context): Type =
+      val arg :: Nil = tree.args: @unchecked
+      val argType0 = recheck(arg, pt.stripCapturing.capturing(FreshCap(Origin.UnsafeAssumePure)))
+      val argType =
+        if argType0.captureSet.isAlwaysEmpty then argType0
+        else argType0.widen.stripCapturing
+      capt.println(i"rechecking unsafeAssumePure of $arg with $pt: $argType")
+      super.recheckFinish(argType, tree, pt)
+
+    /** Recheck `caps.freeze(...)` */
+    def applyFreeze(tree: Apply)(using Context): Type =
+      val arg :: Nil = tree.args: @unchecked
+      def imm = new TypeMap:
+        def apply(t: Type) = t match
+          case t @ CapturingType(parent, _)
+          if parent.derivesFromMutable && variance > 0 =>
+            t.derivedCapturingType(apply(parent), CaptureSet.emptyOfStateful)
+          case _ =>
+            mapOver(t)
+      val opProto = // () ?-> <?>
+        defn.FunctionType(0, isContextual = true).appliedTo(WildcardType)
+      recheck(arg, opProto).stripCapturing match
+        case defn.ContextFunctionType(Nil, resType) => imm(resType)
+
+    /** Recheck applications, with special handling of unsafeAssumePure,
+     *  unsafeDiscardUses, and freeze.
      *  More work is done in `recheckApplication`, `recheckArg` and `instantiate` below.
      */
     override def recheckApply(tree: Apply, pt: Type)(using Context): Type =
       val meth = tree.fun.symbol
       if meth == defn.Caps_unsafeAssumePure then
-        val arg :: Nil = tree.args: @unchecked
-        val argType0 = recheck(arg, pt.stripCapturing.capturing(FreshCap(Origin.UnsafeAssumePure)))
-        val argType =
-          if argType0.captureSet.isAlwaysEmpty then argType0
-          else argType0.widen.stripCapturing
-        capt.println(i"rechecking unsafeAssumePure of $arg with $pt: $argType")
-        super.recheckFinish(argType, tree, pt)
+        applyAssumePure(tree, pt)
       else if meth == defn.Caps_unsafeDiscardUses then
         val arg :: Nil = tree.args: @unchecked
         withDiscardedUses(recheck(arg, pt))
+      else if meth == defn.Caps_freeze then
+        applyFreeze(tree)
       else
         val res = super.recheckApply(tree, pt)
         includeCallCaptures(meth, res, tree)

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

@@ -1028,6 +1028,7 @@ class Definitions {
     @tu lazy val Caps_ContainsTrait: TypeSymbol = CapsModule.requiredType("Contains")
     @tu lazy val Caps_ContainsModule: Symbol = requiredModule("scala.caps.Contains")
     @tu lazy val Caps_containsImpl: TermSymbol = Caps_ContainsModule.requiredMethod("containsImpl")
+    @tu lazy val Caps_freeze: TermSymbol = CapsModule.requiredMethod("freeze")
 
   @tu lazy val PureClass: ClassSymbol = requiredClass("scala.caps.Pure")
 
@@ -2098,7 +2099,7 @@ class Definitions {
     RequiresCapabilityAnnot,
     captureRoot, Caps_CapSet, Caps_ContainsTrait, Caps_ContainsModule, Caps_ContainsModule.moduleClass,
     ConsumeAnnot, UseAnnot, ReserveAnnot,
-    CapsUnsafeModule, CapsUnsafeModule.moduleClass,
+    CapsUnsafeModule, CapsUnsafeModule.moduleClass, Caps_freeze,
     CapsInternalModule, CapsInternalModule.moduleClass,
     RetainsAnnot, RetainsCapAnnot, RetainsByNameAnnot)
 

docs/_docs/reference/experimental/capture-checking/mutability.md

@@ -444,3 +444,35 @@ The subcapturing theory for sets is then as before, with the following additiona
  - `C₁.reader <: C₂.reader` if `C₍ <: C₂`
  - `{x, ...}.reader = {x.rd, ...}.reader`
  - `{x.rd, ...} <: {x, ...}`
+
+## The `freeze` Wrapper
+
+We often want to create a mutable data structure like an array, initialize by assigning to its elements and then return the array as an immutable type that does not
+capture any capabilities. This can be achieved using the `freeze` wrapper.
+
+As an example, consider a class `Arr` which is modelled after `Array` and its immutable counterpart `IArr`:
+
+```scala
+class Arr[T: reflect.ClassTag](len: Int) extends Mutable:
+  private val arr: Array[T] = new Array[T](len)
+  def get(i: Int): T = arr(i)
+  update def update(i: Int, x: T): Unit = arr(i) = x
+type IArr[T] = Arr[T]^{}
+```
+
+The `freeze` wrapper allows us to go from an `Arr` to an `IArr`, safely:
+```scala
+import caps.freeze
+
+val f: IArr[String] = freeze:
+  val a = Arr[String](2)
+  a(0) = "hello"
+  a(1) = "world"
+  a
+```
+The `freeze` method is defined in `caps` like this:
+```scala
+def freeze[T](op: -> T): T = op
+```
+It takes a pure by-name parameter and returns its result. But the actual return type after capture checking is special. Instead of just `T` as in the declaration above suggests, it's `T` where every covariant occurrence of a `Mutable` type gets its capture set mapped to `{}`.
+

library/src/scala/caps/package.scala

@@ -141,6 +141,7 @@ final class reserve extends annotation.StaticAnnotation
  *  environment.
  */
 @experimental
+@deprecated(since = "3.8.0")
 final class use extends annotation.StaticAnnotation
 
 /** A trait that used to allow expressing existential types. Replaced by
@@ -150,6 +151,12 @@ final class use extends annotation.StaticAnnotation
 @deprecated
 sealed trait Exists extends Capability
 
+/** A wrapper that strips all covariant capture sets from Mutable types in the
+ *  result of pure operation `op`, turning them into immutable types.
+ */
+@experimental
+def freeze[T](op: -> T): T = op
+
 @experimental
 object internal:
 

tests/neg-custom-args/captures/freeze.check

@@ -0,0 +1,22 @@
+-- [E007] Type Mismatch Error: tests/neg-custom-args/captures/freeze.scala:13:17 ---------------------------------------
+13 |  val b = freeze(a) // error
+   |                 ^
+   |                 Found:    () ?->{a} Arr[String]^{a}
+   |                 Required: () ?-> <?>
+   |
+   |                 Note that capability a is not included in capture set {}.
+   |
+   | longer explanation available when compiling with `-explain`
+-- [E007] Type Mismatch Error: tests/neg-custom-args/captures/freeze.scala:22:4 ----------------------------------------
+21 |  freeze:
+22 |    mkExclusive() // error
+   |  ^
+   |  Capability cap outlives its scope: it leaks into outer capture set 's1 of method test3.
+   |  The leakage occurred when trying to match the following types:
+   |
+   |  Found:    EX^{cap}
+   |  Required: EX^'s1
+   |
+   |  where:    cap is a root capability associated with the result type of (): EX^
+   |
+   | longer explanation available when compiling with `-explain`

tests/neg-custom-args/captures/freeze.scala

@@ -0,0 +1,23 @@
+import caps.*
+
+class Arr[T: reflect.ClassTag](len: Int) extends Mutable:
+  private val arr: Array[T] = new Array[T](len)
+  def get(i: Int): T = arr(i)
+  update def update(i: Int, x: T): Unit = arr(i) = x
+
+
+def test2 =
+  val a = Arr[String](2)
+  a(0) = "1"
+  a(1) = "2"
+  val b = freeze(a) // error
+  b
+
+class EX
+
+def mkExclusive(): EX^ = ???
+
+def test3 =
+  freeze:
+    mkExclusive() // error
+

tests/pending/pos-custom-args/captures/freeze-cycle.scala

@@ -0,0 +1,15 @@
+import caps.*
+
+class Node(val payload: Int) extends Mutable:
+  var next: Node = ???
+
+
+type INode = Node^{}
+
+def cycle(x: Int, y: Int): (INode, INode) =
+  freeze:
+    val a = Node(x)
+    val b = Node(y)
+    a.next = b
+    b.next = a
+    (a, b)

tests/pos-custom-args/captures/freeze.scala

@@ -0,0 +1,26 @@
+import language.experimental.captureChecking
+import caps.*
+
+class Arr[T: reflect.ClassTag](len: Int) extends Mutable:
+  private val arr: Array[T] = new Array[T](len)
+  def get(i: Int): T = arr(i)
+  update def update(i: Int, x: T): Unit = arr(i) = x
+
+
+def test2 =
+  val a = freeze:
+    val a = Arr[String](2)
+    a(0) = "1"
+    a(1) = "2"
+    a
+  val _: Arr[String]^{} = a
+
+  val a2 = freeze:
+    val a = Arr[String](2)
+    val b = Arr[String](2)
+    a(0) = "1"
+    a(1) = "2"
+    b(0) = "1"
+    b(1) = "2"
+    (a, b)
+  val _: (Arr[String]^{}, Arr[String]^{}) = a2

tests/run-tasty-inspector/stdlibExperimentalDefinitions.scala

@@ -49,6 +49,7 @@ val experimentalDefinitionInLibrary = Set(
   "scala.caps.unsafe$",
   "scala.caps.use",
   "scala.caps.reserve",
+  "scala.caps.package$package$.freeze",
   "scala.caps.package$package$.Exclusive",
   "scala.caps.package$package$.Shared",