scala3-compiler-bootstrapped
DocsAPI
Generated with
Copyright (c) 2002-2025, LAMP/EPFL
Copyright (c) 2002-2025, LAMP/EPFL
scala3-compiler-bootstrapped/dotty.tools/dotty.tools.dotc/dotty.tools.dotc.cc

dotty.tools.dotc.cc

package dotty.tools.dotc.cc

Members list

Type members

Classlikes

abstract class AnnotatedCapability(annotCls: Context ?=> ClassSymbol)

A base class for extractors that match annotated types with a specific Capability annotation.

A base class for extractors that match annotated types with a specific Capability annotation.

Attributes

Supertypes
class Object
trait Matchable
class Any
Known subtypes
class CCState

Capture checking state, which is known to other capture checking components

Capture checking state, which is known to other capture checking components

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
object CCState

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
CCState.type
object Capabilities

Capabilities are members of capture sets. They partially overlap with types as shown in the trait hierarchy below.

Capabilities are members of capture sets. They partially overlap with types as shown in the trait hierarchy below.

Capability --+-- RootCapabilty -----+-- GlobalCap | +-- FreshCap | +-- ResultCap | +-- CoreCapability ----+-- ObjectCapability --+-- TermRef | | +-- ThisType | | +-- TermParamRef | | | +-- SetCapability -----+-- TypeRef | +-- TypeParamRef | +-- DerivedCapability -+-- ReadOnly +-- Reach +-- Maybe

All CoreCapabilities are Types, or, more specifically instances of TypeProxy.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
case class CaptureAnnotation(refs: CaptureSet, boxed: Boolean)(cls: Symbol) extends Annotation

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.

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.

Value parameters

boxed

whether the type carrying the annotation is boxed

cls

the underlying class (either annotation.retains or annotation.retainsByName)

refs

the capture set

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Annotation
trait Showable
class Object
trait Matchable
class Any
Show all
trait CaptureRunInfo

Attributes

Supertypes
class Object
trait Matchable
class Any
Known subtypes
class Run
class TASTYRun
Self type
Run
sealed abstract class CaptureSet extends Showable

A class for capture sets. Capture sets can be constants or variables. Capture sets support inclusion constraints <:< where <:< is subcapturing.

A class for capture sets. Capture sets can be constants or variables. Capture sets support inclusion constraints <:< where <:< is subcapturing.

They also allow

  • mapping with functions from elements to capture sets
  • filtering with predicates on elements
  • intersecting wo capture sets

That is, constraints can be of the forms

cs1 <:< cs2 cs1 = ∪ {f(x) | x ∈ cs2} where f is a function from capabilities to capture sets. cs1 = ∪ {x | x ∈ cs2, p(x)} where p is a predicate on capabilities cs1 = cs2 ∩ cs2

We call the resulting constraint system "monadic set constraints". To support capture propagation across maps, mappings are supported only if the mapped function is either a bijection or if it is idempotent on capabilities (c.f. doc comment on map below).

Attributes

Companion
object
Supertypes
trait Showable
class Object
trait Matchable
class Any
Known subtypes
class Const
object Fluid
class Var
class DerivedVar
class BiMapped
class Filtered
class Diff
class HiddenSet
class RefiningVar
Show all
object CaptureSet

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
CaptureSet.type
object CapturingOrRetainsType

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
object CapturingType

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.

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.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
object CheckCaptures

The capture checker

The capture checker

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
class CheckCaptures extends Recheck, SymTransformer

Attributes

Companion
object
Supertypes
class Recheck
class Phase
class Object
trait Matchable
class Any
Show all
Self type
class CleanupRetains(using x$1: Context) extends TypeMap

Drop retains annotations in the type.

Drop retains annotations in the type.

Attributes

Supertypes
class TypeMap
trait Type => Type
class Object
trait Matchable
class Any
Show all
object ContainsImpl

An extractor for a contains argument

An extractor for a contains argument

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
object ContainsParam

An extractor for a contains parameter

An extractor for a contains parameter

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
abstract class DeepTypeAccumulator[T](using x$1: Context) extends TypeAccumulator[T]

A class encapsulating the assumulator logic needed for CaptureSet.ofTypeDeeply and derivesFromCapTraitDeeply. NOTE: The traversal logic needs to be in sync with narrowCaps in CaptureOps, which replaces caps with reach capabilties. There are two exceptions, however.

A class encapsulating the assumulator logic needed for CaptureSet.ofTypeDeeply and derivesFromCapTraitDeeply. NOTE: The traversal logic needs to be in sync with narrowCaps in CaptureOps, which replaces caps with reach capabilties. There are two exceptions, however.

  • First, invariant arguments. These have to be included to be conservative in dcs but must be excluded in narrowCaps.
  • Second, unconstrained type variables are handled specially in ofTypeDeeply.

Attributes

Supertypes
class TypeAccumulator[T]
trait (T, Type) => T
class Object
trait Matchable
class Any
Show all
object FunctionOrMethod

An extractor for all kinds of function types as well as method and poly types. It includes aliases of function types such as =>. TODO: Can we do without?

An extractor for all kinds of function types as well as method and poly types. It includes aliases of function types such as =>. TODO: Can we do without?

Attributes

Returns

1st half: The argument types or empty if this is a type function 2nd half: The result type

Supertypes
class Object
trait Matchable
class Any
Self type
class IllegalCaptureRef(tpe: Type)(using x$2: Context) extends Exception

An exception thrown if a @retains argument is not syntactically a Capability

An exception thrown if a @retains argument is not syntactically a Capability

Attributes

Supertypes
class Exception
class Throwable
trait Serializable
class Object
trait Matchable
class Any
Show all
object MaybeCapability extends AnnotatedCapability

An extractor for ref @amaybeCapability, which is used to express the maybe capability ref? as a type.

An extractor for ref @amaybeCapability, which is used to express the maybe capability ref? as a type.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
object ReachCapability extends AnnotatedCapability

An extractor for ref @reachCapability, which is used to express the reach capability ref* as a type.

An extractor for ref @reachCapability, which is used to express the reach capability ref* as a type.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
object ReadOnlyCapability extends AnnotatedCapability

An extractor for ref @readOnlyCapability, which is used to express the read-only capability ref.rd as a type.

An extractor for ref @readOnlyCapability, which is used to express the read-only capability ref.rd as a type.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
object RetainingType

A builder and extractor for annotated types with @retains or @retainsByName annotations excluding CapturingTypes.

A builder and extractor for annotated types with @retains or @retainsByName annotations excluding CapturingTypes.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
object SepCheck

The separation checker is a tree traverser that is run after capture checking. It checks tree nodes for various separation conditions, explained in the methods below. Rough summary:

The separation checker is a tree traverser that is run after capture checking. It checks tree nodes for various separation conditions, explained in the methods below. Rough summary:

  • Hidden sets of arguments must not be referred to in the same application
  • Hidden sets of (result-) types must not be referred to alter in the same scope.
  • Returned hidden sets can only refer to @consume parameters.
  • If returned hidden sets refer to an encloding this, the reference must be from a @consume method.
  • Consumed entities cannot be used subsequently.
  • Entitites cannot be consumed in a loop.

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
SepCheck.type
class SepCheck(checker: CheckerAPI) extends TreeTraverser

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
object Setup

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
Setup.type
class Setup extends PreRecheck, SymTransformer, SetupAPI

Phase that sets up everthing for capture checking.

Phase that sets up everthing for capture checking.

A tree traverser that prepares a compilation unit to be capture checked. It does the following:

  • For every inferred type, drop any retains annotations, add capture sets to all its parts, add refinements to class types and function types. (c.f. mapInferred)
  • For explicit capturing types, expand throws aliases to the underlying (pure) function, and add some implied capture sets to curried functions (c.f. expandThrowsAlias, expandAbbreviations).
  • Add capture sets to self types of classes and objects, unless the self type was written explicitly.
  • Box the types of mutable variables and type arguments to methods (type arguments of types are boxed on access).
  • Link the external types of val and def symbols with the inferred types based on their parameter symbols.

Attributes

Companion
object
Supertypes
trait SetupAPI
class PreRecheck
class Phase
class Object
trait Matchable
class Any
Show all
Self type
trait SetupAPI

Operations accessed from CheckCaptures

Operations accessed from CheckCaptures

Attributes

Supertypes
class Object
trait Matchable
class Any
Known subtypes
class Setup
object Synthetics

Classification and transformation methods for function methods and synthetic case class methods that need to be treated specially. In particular, compute capturing types for some of these methods which have inferred (result-)types that need to be established under separate compilation.

Classification and transformation methods for function methods and synthetic case class methods that need to be treated specially. In particular, compute capturing types for some of these methods which have inferred (result-)types that need to be established under separate compilation.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
Synthetics.type
object ccConfig

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
ccConfig.type

Value members

Concrete methods

def ccState(using Context): CCState

The currently valid CCState

The currently valid CCState

Attributes

def depFun(args: List[Type], resultType: Type, isContextual: Boolean, paramNames: List[TermName])(using Context): Type

A dependent function type with given arguments and result type TODO Move somewhere else where we treat all function type related ops together.

A dependent function type with given arguments and result type TODO Move somewhere else where we treat all function type related ops together.

Attributes

def isCaptureChecking(using Context): Boolean

Are we at checkCaptures phase?

Are we at checkCaptures phase?

Attributes

def isCaptureCheckingOrSetup(using Context): Boolean

Are we in the CheckCaptures or Setup phase?

Are we in the CheckCaptures or Setup phase?

Attributes

Extensions

Extensions

extension (self: Type)
def derivedFunctionOrMethod(argTypes: List[Type], resType: Type)(using Context): Type

If tp is a function or method, a type of the same kind with the given argument and result types.

If tp is a function or method, a type of the same kind with the given argument and result types.

Attributes

extension (sym: Symbol)
def allowsRootCapture(using Context): Boolean

Does this symbol allow results carrying the universal capability? Currently this is true only for function type applies (since their results are unboxed) and erasedValue since this function is magic in that is allows to conjure global capabilies from nothing (aside: can we find a more controlled way to achieve this?). But it could be generalized to other functions that so that they can take capability classes as arguments.

Does this symbol allow results carrying the universal capability? Currently this is true only for function type applies (since their results are unboxed) and erasedValue since this function is magic in that is allows to conjure global capabilies from nothing (aside: can we find a more controlled way to achieve this?). But it could be generalized to other functions that so that they can take capability classes as arguments.

Attributes

def isConsumeParam(using Context): Boolean

sym or its info is annotated with @consume.

sym or its info is annotated with @consume.

Attributes

def isPureClass(using Context): Boolean

A class is pure if:

A class is pure if:

  • one its base types has an explicitly declared self type with an empty capture set
  • or it is a value class
  • or it is an exception
  • or it is one of Nothing, Null, or String

Attributes

def isRefiningParamAccessor(using Context): Boolean

It's a parameter accessor that is not annotated @constructorOnly or @uncheckedCaptures

It's a parameter accessor that is not annotated @constructorOnly or @uncheckedCaptures

Attributes

def isRetains(using Context): Boolean

This symbol is one of retains or retainsCap

This symbol is one of retains or retainsCap

Attributes

def isRetainsLike(using Context): Boolean

This symbol is one of retains, retainsCap, orretainsByName

This symbol is one of retains, retainsCap, orretainsByName

Attributes

def isUseParam(using Context): Boolean

sym itself or its info is annotated @use or it is a type parameter with a matching

sym itself or its info is annotated @use or it is a type parameter with a matching

Attributes

def unboxesResult(using Context): Boolean

When applying sym, would the result type be unboxed? This is the case if the result type contains a top-level reference to an enclosing class or method type parameter and the method does not allow root capture. If the type parameter is instantiated to a boxed type, that type would have to be unboxed in the method's result.

When applying sym, would the result type be unboxed? This is the case if the result type contains a top-level reference to an enclosing class or method type parameter and the method does not allow root capture. If the type parameter is instantiated to a boxed type, that type would have to be unboxed in the method's result.

Attributes

extension (tp: Type)
def boxed(using Context): Type

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.

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.

Attributes

def boxedCaptureSet(using Context): CaptureSet

The capture set consisting of all top-level captures of tp that appear under a box. Unlike for boxed this also considers parents of capture types, unions and intersections, and type proxies other than abstract types. Furthermore, if the original type is a capability x, it replaces boxed universal sets on the fly with x*.

The capture set consisting of all top-level captures of tp that appear under a box. Unlike for boxed this also considers parents of capture types, unions and intersections, and type proxies other than abstract types. Furthermore, if the original type is a capability x, it replaces boxed universal sets on the fly with x*.

Attributes

final def captureSet(using Context): CaptureSet

The capture set of a type. This is:

The capture set of a type. This is:

  • For object capabilities: The singleton capture set consisting of just the reference, provided the underlying capture set of their info is not empty.
  • For other capabilities: The capture set of their info
  • For all other types: The result of CaptureSet.ofType

Attributes

def capturing(ref: Capability)(using Context): Type

A type capturing ref

A type capturing ref

Attributes

def capturing(cs: CaptureSet)(using Context): Type

A type capturing the capture set cs. If this type is already a capturing type the two capture sets are combined.

A type capturing the capture set cs. If this type is already a capturing type the two capture sets are combined.

Attributes

def containsCap(using Context): Boolean

Does this type contain no-flip covariant occurrences of cap?

Does this type contain no-flip covariant occurrences of cap?

Attributes

def deepCaptureSet(includeTypevars: Boolean)(using Context): CaptureSet

The deep capture set of a type. This is by default the union of all covariant capture sets embedded in the widened type, as computed by CaptureSet.ofTypeDeeply. If that set is nonempty, and the type is a singleton capability x or a reach capability x*, the deep capture set can be narrowed to{x*}.

The deep capture set of a type. This is by default the union of all covariant capture sets embedded in the widened type, as computed by CaptureSet.ofTypeDeeply. If that set is nonempty, and the type is a singleton capability x or a reach capability x*, the deep capture set can be narrowed to{x*}.

Attributes

def derivedCapturingType(parent: Type, refs: CaptureSet)(using Context): Type

Attributes

def derivesFromCapTrait(cls: ClassSymbol)(using Context): Boolean

Tests whether the type derives from capability class cls.

Tests whether the type derives from capability class cls.

Attributes

def derivesFromCapTraitDeeply(cls: ClassSymbol)(using Context): Boolean

Tests whether all CapturingType parts of the type that are traversed for dcs computation satisfy at least one of two conditions:

Tests whether all CapturingType parts of the type that are traversed for dcs computation satisfy at least one of two conditions:

  1. They decorate classes that extend the given capability class cls, or
  2. Their capture set is constant and consists only of capabilities the derive from cls in the sense of derivesFromCapTrait.

Attributes

def dropAllRetains(using Context): Type

Drop @retains annotations everywhere

Drop @retains annotations everywhere

Attributes

def forceBoxStatus(boxed: Boolean)(using Context): Type

If this type is a capturing type, the version with boxed statues as given by boxed. If it is a TermRef of a capturing type, and the box status flips, widen to a capturing type that captures the TermRef.

If this type is a capturing type, the version with boxed statues as given by boxed. If it is a TermRef of a capturing type, and the box status flips, widen to a capturing type that captures the TermRef.

Attributes

def isAliasFun(using Context): Boolean

Knowing that tp is a function type, is it an alias to a function other than =>?

Knowing that tp is a function type, is it an alias to a function other than =>?

Attributes

def isAlwaysPure(using Context): Boolean

Is type known to be always pure by its class structure? In that case, adding a capture set to it would not make sense.

Is type known to be always pure by its class structure? In that case, adding a capture set to it would not make sense.

Attributes

def isBoxCompatibleWith(tp2: Type)(using Context): Boolean

Is the box status of tp and tp2 compatible? I.ee they are box boxed, or both unboxed, or one of them has an empty capture set.

Is the box status of tp and tp2 compatible? I.ee they are box boxed, or both unboxed, or one of them has an empty capture set.

Attributes

def isBoxedCapturing(using Context): Boolean

Is the boxedCaptureSet of this type nonempty?

Is the boxedCaptureSet of this type nonempty?

Attributes

def isCapRef(using Context): Boolean

Is this a reference to caps.cap? Note this is not the GlobalCap capability.

Is this a reference to caps.cap? Note this is not the GlobalCap capability.

Attributes

def isMutableType(using Context): Boolean

Is this a type extending Mutable that has update methods?

Is this a type extending Mutable that has update methods?

Attributes

final def isTrackableRef(using Context): Boolean

Is this type a Capability that can be tracked? This is true for

Is this type a Capability that can be tracked? This is true for

  • all ThisTypes and all TermParamRef,
  • stable TermRefs with NoPrefix or ThisTypes as prefixes,
  • annotated types that represent reach or maybe capabilities

Attributes

def refinedOverride(name: Name, rinfo: Type)(using Context): Type
def retainedElements(using Context): List[Capability]

A list of capabilities of a retained set.

A list of capabilities of a retained set.

Attributes

def retainedElementsRaw(using Context): List[Type]

A list of raw elements of a retained set. This will not crash even if it contains a non-wellformed Capability.

A list of raw elements of a retained set. This will not crash even if it contains a non-wellformed Capability.

Attributes

def stripCapturing(using Context): Type

Map capturing type to their parents. Capturing types accessible via dealising are also stripped.

Map capturing type to their parents. Capturing types accessible via dealising are also stripped.

Attributes

def unboxed(using Context): Type

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.

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.

Attributes

def withReachCaptures(ref: Type)(using Context): Type

If x is a capability, replace all no-flip covariant occurrences of cap in type tp with x*.

If x is a capability, replace all no-flip covariant occurrences of cap in type tp with x*.

Attributes

extension (tp: MethodType)
def marksExistentialScope(using Context): Boolean

A method marks an existential scope unless it is the prefix of a curried method

A method marks an existential scope unless it is the prefix of a curried method

Attributes

extension (tp: AnnotatedType)
def isBoxed(using Context): Boolean

Is this a boxed capturing type?

Is this a boxed capturing type?

Attributes

extension (tree: Tree)
def retainedSet(using Context): Type

The type representing the capture set of @retains, @retainsCap or @retainsByName annotation.

The type representing the capture set of @retains, @retainsCap or @retainsByName annotation.

Attributes

def toCaptureSet(using Context): CaptureSet

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.

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.

Attributes

Generated with
Copyright (c) 2002-2025, LAMP/EPFL
Copyright (c) 2002-2025, LAMP/EPFL