Skip to content

Commit e4cd634

Browse files
WojciechMazurWojciechMazur
committed
Changes in preparation to make caps.Capability stable (#22849)
Make `scala.caps` a package instead of an object. The following are still under `scala.caps`, while staying `@experimental`: - The Capability trait, which will be stable in near future - The universal capture reference `cap` -- **now an object**. - The carrier trait for capture set parameters `CapSet` - The `Contains` trait: - Due to `given`s cannot be marked `@experimental`, an experimental `Contains` object was created instead, which contains the `containsImpl` given. - Exclusive capabilities annotations: `Mutable`, `SharedCapability` and `consume` - The _`Exists`_ trait is marked `deprecated`, but is required to build the current version of the compiler. It should be removed in the next version. - The `unsafe` object: - `untrackedCaptures` is moved into `caps.unsafe`. - Deprecated aliases `*` and `Cap` are **removed** The following are moved under the experimental `scala.caps.internal` object: - `capsOf` - `rootCapability`, `reachCapability` and `readOnlyCapability` - `refineOverride` Add documentation for `Capability` and some other experimental annotations. Tests are updated accordingly. [Cherry-picked f177289][modified]
1 parent d112546 commit e4cd634

File tree

15 files changed

+203
-91
lines changed

15 files changed

+203
-91
lines changed

‎compiler/src/dotty/tools/dotc/ast/untpd.scala

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -518,14 +518,17 @@ object untpd extends Trees.Instance[Untyped] with UntypedTreeInfo {
518518
def scalaUnit(implicit src: SourceFile): Select = scalaDot(tpnme.Unit)
519519
def scalaAny(implicit src: SourceFile): Select = scalaDot(tpnme.Any)
520520

521+
def capsInternalDot(name: Name)(using SourceFile): Select =
522+
Select(Select(scalaDot(nme.caps), nme.internal), name)
523+
521524
def captureRoot(using Context): Select =
522525
Select(scalaDot(nme.caps), nme.CAPTURE_ROOT)
523526

524527
def makeRetaining(parent: Tree, refs: List[Tree], annotName: TypeName)(using Context): Annotated =
525528
Annotated(parent, New(scalaAnnotationDot(annotName), List(refs)))
526529

527530
def makeCapsOf(tp: RefTree)(using Context): Tree =
528-
TypeApply(Select(scalaDot(nme.caps), nme.capsOf), tp :: Nil)
531+
TypeApply(capsInternalDot(nme.capsOf), tp :: Nil)
529532

530533
// Capture set variable `[C^]` becomes: `[C >: CapSet <: CapSet^{cap}]`
531534
def makeCapsBound()(using Context): TypeBoundsTree =

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

Lines changed: 19 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -993,17 +993,21 @@ class Definitions {
993993
@tu lazy val LabelClass: Symbol = requiredClass("scala.util.boundary.Label")
994994
@tu lazy val BreakClass: Symbol = requiredClass("scala.util.boundary.Break")
995995

996-
@tu lazy val CapsModule: Symbol = requiredModule("scala.caps")
996+
@tu lazy val CapsModule: Symbol = requiredPackage("scala.caps")
997997
@tu lazy val captureRoot: TermSymbol = CapsModule.requiredValue("cap")
998998
@tu lazy val Caps_Capability: TypeSymbol = CapsModule.requiredType("Capability")
999999
@tu lazy val Caps_CapSet: ClassSymbol = requiredClass("scala.caps.CapSet")
1000-
@tu lazy val Caps_reachCapability: TermSymbol = CapsModule.requiredMethod("reachCapability")
1001-
@tu lazy val Caps_capsOf: TermSymbol = CapsModule.requiredMethod("capsOf")
1002-
@tu lazy val Caps_Exists: ClassSymbol = requiredClass("scala.caps.Exists")
1000+
@tu lazy val CapsInternalModule: Symbol = requiredModule("scala.caps.internal")
1001+
@tu lazy val Caps_reachCapability: TermSymbol = CapsInternalModule.requiredMethod("reachCapability")
1002+
@tu lazy val Caps_readOnlyCapability: TermSymbol = CapsInternalModule.requiredMethod("readOnlyCapability")
1003+
@tu lazy val Caps_capsOf: TermSymbol = CapsInternalModule.requiredMethod("capsOf")
10031004
@tu lazy val CapsUnsafeModule: Symbol = requiredModule("scala.caps.unsafe")
10041005
@tu lazy val Caps_unsafeAssumePure: Symbol = CapsUnsafeModule.requiredMethod("unsafeAssumePure")
10051006
@tu lazy val Caps_ContainsTrait: TypeSymbol = CapsModule.requiredType("Contains")
1006-
@tu lazy val Caps_containsImpl: TermSymbol = CapsModule.requiredMethod("containsImpl")
1007+
@tu lazy val Caps_ContainsModule: Symbol = requiredModule("scala.caps.Contains")
1008+
@tu lazy val Caps_containsImpl: TermSymbol = Caps_ContainsModule.requiredMethod("containsImpl")
1009+
@tu lazy val Caps_Mutable: ClassSymbol = requiredClass("scala.caps.Mutable")
1010+
@tu lazy val Caps_SharedCapability: ClassSymbol = requiredClass("scala.caps.SharedCapability")
10071011

10081012
/** The same as CaptureSet.universal but generated implicitly for references of Capability subtypes */
10091013
@tu lazy val universalCSImpliedByCapability = CaptureSet(captureRoot.termRef)
@@ -1063,8 +1067,10 @@ class Definitions {
10631067
@tu lazy val UncheckedStableAnnot: ClassSymbol = requiredClass("scala.annotation.unchecked.uncheckedStable")
10641068
@tu lazy val UncheckedVarianceAnnot: ClassSymbol = requiredClass("scala.annotation.unchecked.uncheckedVariance")
10651069
@tu lazy val UncheckedCapturesAnnot: ClassSymbol = requiredClass("scala.annotation.unchecked.uncheckedCaptures")
1066-
@tu lazy val UntrackedCapturesAnnot: ClassSymbol = requiredClass("scala.caps.untrackedCaptures")
1070+
@tu lazy val UntrackedCapturesAnnot: ClassSymbol = requiredClass("scala.caps.unsafe.untrackedCaptures")
10671071
@tu lazy val UseAnnot: ClassSymbol = requiredClass("scala.caps.use")
1072+
@tu lazy val ConsumeAnnot: ClassSymbol = requiredClass("scala.caps.consume")
1073+
@tu lazy val RefineOverrideAnnot: ClassSymbol = requiredClass("scala.caps.internal.refineOverride")
10681074
@tu lazy val VolatileAnnot: ClassSymbol = requiredClass("scala.volatile")
10691075
@tu lazy val LanguageFeatureMetaAnnot: ClassSymbol = requiredClass("scala.annotation.meta.languageFeature")
10701076
@tu lazy val BeanGetterMetaAnnot: ClassSymbol = requiredClass("scala.annotation.meta.beanGetter")
@@ -1080,6 +1086,8 @@ class Definitions {
10801086
@tu lazy val TargetNameAnnot: ClassSymbol = requiredClass("scala.annotation.targetName")
10811087
@tu lazy val VarargsAnnot: ClassSymbol = requiredClass("scala.annotation.varargs")
10821088
@tu lazy val ReachCapabilityAnnot = requiredClass("scala.annotation.internal.reachCapability")
1089+
@tu lazy val RootCapabilityAnnot = requiredClass("scala.caps.internal.rootCapability")
1090+
@tu lazy val ReadOnlyCapabilityAnnot = requiredClass("scala.annotation.internal.readOnlyCapability")
10831091
@tu lazy val RequiresCapabilityAnnot: ClassSymbol = requiredClass("scala.annotation.internal.requiresCapability")
10841092
@tu lazy val RetainsAnnot: ClassSymbol = requiredClass("scala.annotation.retains")
10851093
@tu lazy val RetainsCapAnnot: ClassSymbol = requiredClass("scala.annotation.retainsCap")
@@ -2087,7 +2095,12 @@ class Definitions {
20872095
*/
20882096
@tu lazy val ccExperimental: Set[Symbol] = Set(
20892097
CapsModule, CapsModule.moduleClass, PureClass,
2098+
Caps_Capability, // TODO: Remove when Capability is stabilized
20902099
RequiresCapabilityAnnot,
2100+
captureRoot, Caps_CapSet, Caps_ContainsTrait, Caps_ContainsModule, Caps_ContainsModule.moduleClass, UseAnnot,
2101+
Caps_Mutable, Caps_SharedCapability, ConsumeAnnot,
2102+
CapsUnsafeModule, CapsUnsafeModule.moduleClass,
2103+
CapsInternalModule, CapsInternalModule.moduleClass,
20912104
RetainsAnnot, RetainsCapAnnot, RetainsByNameAnnot)
20922105

20932106
/** Experimental language features defined in `scala.runtime.stdLibPatches.language.experimental`.

‎compiler/src/dotty/tools/dotc/printing/PlainPrinter.scala

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -187,10 +187,11 @@ class PlainPrinter(_ctx: Context) extends Printer {
187187
homogenize(tp) match {
188188
case tp: TypeType =>
189189
toTextRHS(tp)
190+
case tp: TermRef if tp.isCap =>
191+
toTextCaptureRef(tp)
190192
case tp: TermRef
191193
if !tp.denotationIsCurrent
192194
&& !homogenizedView // always print underlying when testing picklers
193-
&& !tp.isRootCapability
194195
|| tp.symbol.is(Module)
195196
|| tp.symbol.name == nme.IMPORT =>
196197
toTextRef(tp) ~ ".type"

‎library/src/scala/caps.scala

Lines changed: 0 additions & 69 deletions
This file was deleted.

‎library/src/scala/caps/package.scala

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
package scala
2+
package caps
3+
4+
import annotation.{experimental, compileTimeOnly, retainsCap}
5+
6+
/**
7+
* Base trait for classes that represent capabilities in the
8+
* [object-capability model](https://en.wikipedia.org/wiki/Object-capability_model).
9+
*
10+
* A capability is a value representing a permission, access right, resource or effect.
11+
* Capabilities are typically passed to code as parameters; they should not be global objects.
12+
* Often, they come with access restrictions such as scoped lifetimes or limited sharing.
13+
*
14+
* An example is the [[scala.util.boundary.Label Label]] class in [[scala.util.boundary]].
15+
* It represents a capability in the sense that it gives permission to [[scala.util.boundary.break break]]
16+
* to the enclosing boundary represented by the `Label`. It has a scoped lifetime, since breaking to
17+
* a `Label` after the associated `boundary` was exited gives a runtime exception.
18+
*
19+
* [[Capability]] has a formal meaning when
20+
* [[scala.language.experimental.captureChecking Capture Checking]]
21+
* is turned on.
22+
* But even without capture checking, extending this trait can be useful for documenting the intended purpose
23+
* of a class.
24+
*/
25+
@experimental
26+
trait Capability extends Any
27+
28+
/** The universal capture reference. */
29+
@experimental
30+
object cap extends Capability
31+
32+
/** Marker trait for classes with methods that requires an exclusive reference. */
33+
@experimental
34+
trait Mutable extends Capability
35+
36+
/** Marker trait for capabilities that can be safely shared in a concurrent context.
37+
* During separation checking, shared capabilities are not taken into account.
38+
*/
39+
@experimental
40+
trait SharedCapability extends Capability
41+
42+
/** Carrier trait for capture set type parameters */
43+
@experimental
44+
trait CapSet extends Any
45+
46+
/** A type constraint expressing that the capture set `C` needs to contain
47+
* the capability `R`
48+
*/
49+
@experimental
50+
sealed trait Contains[+C >: CapSet <: CapSet @retainsCap, R <: Singleton]
51+
52+
@experimental
53+
object Contains:
54+
/** The only implementation of `Contains`. The constraint that `{R} <: C` is
55+
* added separately by the capture checker.
56+
*/
57+
@experimental
58+
given containsImpl[C >: CapSet <: CapSet @retainsCap, R <: Singleton]: Contains[C, R]()
59+
60+
/** An annotation on parameters `x` stating that the method's body makes
61+
* use of the reach capability `x*`. Consequently, when calling the method
62+
* we need to charge the deep capture set of the actual argiment to the
63+
* environment.
64+
*
65+
* Note: This should go into annotations. For now it is here, so that we
66+
* can experiment with it quickly between minor releases
67+
*/
68+
@experimental
69+
final class use extends annotation.StaticAnnotation
70+
71+
/** An annotations on parameters and update methods.
72+
* On a parameter it states that any capabilties passed in the argument
73+
* are no longer available afterwards, unless they are of class `SharableCapabilitty`.
74+
* On an update method, it states that the `this` of the enclosing class is
75+
* consumed, which means that any capabilities of the method prefix are
76+
* no longer available afterwards.
77+
*/
78+
@experimental
79+
final class consume extends annotation.StaticAnnotation
80+
81+
/** A trait that used to allow expressing existential types. Replaced by
82+
* root.Result instances.
83+
*/
84+
@experimental
85+
@deprecated
86+
sealed trait Exists extends Capability
87+
88+
@experimental
89+
object internal:
90+
91+
/** A wrapper indicating a type variable in a capture argument list of a
92+
* @retains annotation. E.g. `^{x, Y^}` is represented as `@retains(x, capsOf[Y])`.
93+
*/
94+
@compileTimeOnly("Should be be used only internally by the Scala compiler")
95+
def capsOf[CS >: CapSet <: CapSet @retainsCap]: Any = ???
96+
97+
/** Reach capabilities x* which appear as terms in @retains annotations are encoded
98+
* as `caps.reachCapability(x)`. When converted to CaptureRef types in capture sets
99+
* they are represented as `x.type @annotation.internal.reachCapability`.
100+
*/
101+
extension (x: Any) def reachCapability: Any = x
102+
103+
/** Read-only capabilities x.rd which appear as terms in @retains annotations are encoded
104+
* as `caps.readOnlyCapability(x)`. When converted to CaptureRef types in capture sets
105+
* they are represented as `x.type @annotation.internal.readOnlyCapability`.
106+
*/
107+
extension (x: Any) def readOnlyCapability: Any = x
108+
109+
/** An internal annotation placed on a refinement created by capture checking.
110+
* Refinements with this annotation unconditionally override any
111+
* info from the parent type, so no intersection needs to be formed.
112+
* This could be useful for tracked parameters as well.
113+
*/
114+
final class refineOverride extends annotation.StaticAnnotation
115+
116+
/** An annotation used internally for root capability wrappers of `cap` that
117+
* represent either Fresh or Result capabilities.
118+
* A capability is encoded as `caps.cap @rootCapability(...)` where
119+
* `rootCapability(...)` is a special kind of annotation of type `root.Annot`
120+
* that contains either a hidden set for Fresh instances or a method type binder
121+
* for Result instances.
122+
*/
123+
final class rootCapability extends annotation.StaticAnnotation
124+
125+
@experimental
126+
object unsafe:
127+
/**
128+
* Marks the constructor parameter as untracked.
129+
* The capture set of this parameter will not be included in
130+
* the capture set of the constructed object.
131+
*
132+
* @note This should go into annotations. For now it is here, so that we
133+
* can experiment with it quickly between minor releases
134+
*/
135+
final class untrackedCaptures extends annotation.StaticAnnotation
136+
137+
extension [T](x: T)
138+
/** A specific cast operation to remove a capture set.
139+
* If argument is of type `T^C`, assume it is of type `T` instead.
140+
* Calls to this method are treated specially by the capture checker.
141+
*/
142+
def unsafeAssumePure: T = x
143+
144+
/** A wrapper around code for which separation checks are suppressed.
145+
*/
146+
def unsafeAssumeSeparate(op: Any): op.type = op
147+
148+
end unsafe

‎scala2-library-cc/src/scala/collection/immutable/LazyListIterable.scala

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,8 @@ import scala.language.implicitConversions
2424
import scala.runtime.Statics
2525
import language.experimental.captureChecking
2626
import annotation.unchecked.uncheckedCaptures
27-
import caps.untrackedCaptures
27+
import caps.cap
28+
import caps.unsafe.{unsafeAssumeSeparate, untrackedCaptures}
2829

2930
/** This class implements an immutable linked list. We call it "lazy"
3031
* because it computes its elements only when they are needed.

‎tests/disabled/neg-custom-args/captures/capt-wf.scala

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
// No longer valid
22
class C
3-
type Cap = C @retains(caps.*)
4-
type Top = Any @retains(caps.*)
3+
type Cap = C @retains(caps.cap)
4+
type Top = Any @retains(caps.cap)
55

66
type T = (x: Cap) => List[String @retains(x)] => Unit // error
77
val x: (x: Cap) => Array[String @retains(x)] = ??? // error

‎tests/disabled/neg-custom-args/captures/try2.scala

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ import annotation.ability
55
@ability erased val canThrow: * = ???
66

77
class CanThrow[E <: Exception] extends Retains[canThrow.type]
8-
type Top = Any @retains(caps.*)
8+
type Top = Any @retains(caps.cap)
99

1010
infix type throws[R, E <: Exception] = (erased CanThrow[E]) ?=> R
1111

‎tests/neg-custom-args/captures/cc-poly-1.check

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
-- [E057] Type Mismatch Error: tests/neg-custom-args/captures/cc-poly-1.scala:12:6 -------------------------------------
22
12 | f[Any](D()) // error
33
| ^
4-
| Type argument Any does not conform to upper bound caps.CapSet^
4+
| Type argument Any does not conform to upper bound scala.caps.CapSet^
55
|
66
| longer explanation available when compiling with `-explain`
77
-- [E057] Type Mismatch Error: tests/neg-custom-args/captures/cc-poly-1.scala:13:6 -------------------------------------
88
13 | f[String](D()) // error
99
| ^
10-
| Type argument String does not conform to upper bound caps.CapSet^
10+
| Type argument String does not conform to upper bound scala.caps.CapSet^
1111
|
1212
| longer explanation available when compiling with `-explain`

‎tests/neg-custom-args/captures/cc-this2.check

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
-- Error: tests/neg-custom-args/captures/cc-this2/D_2.scala:3:8 --------------------------------------------------------
33
3 | this: D^ => // error
44
| ^^
5-
|reference (caps.cap : caps.Capability) captured by this self type is not included in the allowed capture set {} of pure base class class C
5+
| reference cap captured by this self type is not included in the allowed capture set {} of pure base class class C
66
-- [E058] Type Mismatch Error: tests/neg-custom-args/captures/cc-this2/D_2.scala:2:6 -----------------------------------
77
2 |class D extends C: // error
88
| ^

‎tests/neg-custom-args/captures/exception-definitions.check

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
-- Error: tests/neg-custom-args/captures/exception-definitions.scala:3:8 -----------------------------------------------
22
3 | self: Err^ => // error
33
| ^^^^
4-
|reference (caps.cap : caps.Capability) captured by this self type is not included in the allowed capture set {} of pure base class class Throwable
4+
|reference cap captured by this self type is not included in the allowed capture set {} of pure base class class Throwable
55
-- Error: tests/neg-custom-args/captures/exception-definitions.scala:7:12 ----------------------------------------------
66
7 | val x = c // error
77
| ^

‎tests/neg-custom-args/captures/i21313.check

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
-- [E007] Type Mismatch Error: tests/neg-custom-args/captures/i21313.scala:15:12 ---------------------------------------
66
15 | ac1.await(src2) // error
77
| ^^^^
8-
| Found: (src2 : Source[Int, caps.CapSet^{ac2}]^?)
9-
| Required: Source[Int, caps.CapSet^{ac1}]^
8+
| Found: (src2 : Source[Int, scala.caps.CapSet^{ac2}]^?)
9+
| Required: Source[Int, scala.caps.CapSet^{ac1}]^
1010
|
1111
| longer explanation available when compiling with `-explain`

‎tests/pos-custom-args/captures/untracked-captures.scala

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
import caps.untrackedCaptures
1+
import caps.unsafe.untrackedCaptures
2+
23
class LL[+A] private (@untrackedCaptures lazyState: () => LL.State[A]^):
34
private val res = lazyState()
45

‎tests/pos/caps-universal.scala

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import annotation.retains
33

44
val id: Int -> Int = (x: Int) => x
55
val foo: Int => Int = id
6-
val bar: (Int -> Int) @retains(caps.*) = foo
6+
val bar: (Int -> Int) @retains(caps.cap) = foo
77

88

99

0 commit comments

Comments
 (0)