Update CC Docs Until scoped-caps.md #24677

bracevac · 2025-12-05T16:38:19Z

Continuation of #24626

[skip ci]

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

natsukagami · 2025-12-17T18:31:43Z

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

+#### Tracking the evolution of mutable objects
+A common use case for explicit capture parameters is when a mutable object’s reachable capabilities
+_grow_ due to mutation. For example, concatenating effectful iterators:
 ```scala
 class ConcatIterator[A, C^](var iterators: mutable.List[IterableOnce[A]^{C}]):
  def concat(it: IterableOnce[A]^): ConcatIterator[A, {C, it}]^{this, it} =
    iterators ++= it                             //            ^
    this                                         // track contents of `it` in the result
 ```
-In such a scenario, we also should ensure that any pre-existing alias of a `ConcatIterator` object should become
-inaccessible after invoking its `concat` method. This is achieved with [mutation and separation tracking](separation-checking.md) which are currently in development.
+In such cases, the type system must ensure that any existing aliases of the iterator become invalid
+after mutation. This is handled by [mutation tracking](mutability.md) and [separation tracking](separation-checking.md), which are currently under development.


I think this is a poor example, as it instantly leads the reader into writing this (very buggy, doesn't guarantee anything until separation checking) code.

The problem with mutable collections with non-type-parameter element types is that you cannot use implicit capture polymorphism: they get instantiated with the elements at the construction of the collection.

class IteratorList(private var iterators: mutable.List[Iterator[A]^]): // ^ this cap will be instantiated with whatever is in the initial list // ... def +=(it: Iterator[A]^) = iterators += it val xs = IteratorList(mutable.List.empty) // forcefully instantiated to {}

(also we don't have a name to refer to the capture set of the elements, when we write the += method)

Therefore, we need a capture set variable, to allow the user/inference to specify a capture set suitable for the whole usage of the collection.

class IteratorList[C^](private var iterators: mutable.List[Iterator[A]^{C}]): // ... def +=(it: Iterator[A]^{C}) = iterators += it val xs = IteratorList(mutable.List.empty) xs += Iterator(async) xs += Iterator(io) // inference will (probably) find out that xs: IteratorList[{async, io}]

Note that this capture set will not change, it's part of the type: it means you have to be able to name all the captures of all the elements at the point of creating the collection. If you want a growing capture set, it's not sound until separation checking.