Introduce boundary/break control abstraction.

The abstractions are intended to replace the `scala.util.control.Breaks` and
`scala.uitl.control.NonLocalReturns`. They are simpler, safer, and more performant,
since there is a new MiniPhase `DropBreaks` that rewrites local breaks to labeled
returns, i.e. jumps.

The abstractions are not experimental. This break from usual procedure is because
we need to roll them out fast. Non local returns were just deprecated in 3.2, and
we proposed `NonLocalReturns.{returning,throwReturn}` as an alternative. But these
APIs were a mistake and should be deprecated. So rolling out boundary/break now counts
as a bugfix.

Author: odersky

compiler/src/dotty/tools/dotc/Compiler.scala

@@ -87,7 +87,8 @@ class Compiler {
          new sjs.ExplicitJSClasses,  // Make all JS classes explicit (Scala.js only)
          new ExplicitOuter,          // Add accessors to outer classes from nested ones.
          new ExplicitSelf,           // Make references to non-trivial self types explicit as casts
-         new StringInterpolatorOpt) :: // Optimizes raw and s and f string interpolators by rewriting them to string concatenations or formats
+         new StringInterpolatorOpt,  // Optimizes raw and s and f string interpolators by rewriting them to string concatenations or formats
+         new DropBreaks) ::          // Optimize local Break throws by rewriting them 
     List(new PruneErasedDefs,        // Drop erased definitions from scopes and simplify erased expressions
          new UninitializedDefs,      // Replaces `compiletime.uninitialized` by `_`
          new InlinePatterns,         // Remove placeholders of inlined patterns

compiler/src/dotty/tools/dotc/ast/TreeInfo.scala

@@ -102,6 +102,12 @@ trait TreeInfo[T <: Untyped] { self: Trees.Instance[T] =>
     case _ => tree
   }
 
+  def stripTyped(tree: Tree): Tree = unsplice(tree) match
+    case Typed(expr, _) =>
+      stripTyped(expr)
+    case _ =>
+      tree
+
   /** The number of arguments in an application */
   def numArgs(tree: Tree): Int = unsplice(tree) match {
     case Apply(fn, args) => numArgs(fn) + args.length

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

@@ -968,6 +968,9 @@ class Definitions {
   def TupledFunctionClass(using Context): ClassSymbol = TupledFunctionTypeRef.symbol.asClass
   def RuntimeTupleFunctionsModule(using Context): Symbol = requiredModule("scala.runtime.TupledFunctions")
 
+  @tu lazy val LabelClass: Symbol = requiredClass("scala.util.boundary.Label")
+  @tu lazy val BreakClass: Symbol = requiredClass("scala.util.boundary.Break")
+
   @tu lazy val CapsModule: Symbol = requiredModule("scala.caps")
     @tu lazy val captureRoot: TermSymbol = CapsModule.requiredValue("*")
     @tu lazy val CapsUnsafeModule: Symbol = requiredModule("scala.caps.unsafe")

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

@@ -325,6 +325,8 @@ object NameKinds {
 
   val LocalOptInlineLocalObj: UniqueNameKind = new UniqueNameKind("ilo")
 
+  val BoundaryName: UniqueNameKind           = new UniqueNameKind("boundary")
+
   /** The kind of names of default argument getters */
   val DefaultGetterName: NumberedNameKind = new NumberedNameKind(DEFAULTGETTER, "DefaultGetter") {
     def mkString(underlying: TermName, info: ThisInfo) = {

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

@@ -357,6 +357,7 @@ object StdNames {
     val Flag : N                = "Flag"
     val Ident: N                = "Ident"
     val Import: N               = "Import"
+    val Label_this: N           = "Label_this"
     val Literal: N              = "Literal"
     val LiteralAnnotArg: N      = "LiteralAnnotArg"
     val Matchable: N            = "Matchable"
@@ -511,10 +512,12 @@ object StdNames {
     val isInstanceOfPM: N       = "$isInstanceOf$"
     val java: N                 = "java"
     val key: N                  = "key"
+    val label: N                = "label"
     val lang: N                 = "lang"
     val language: N             = "language"
     val length: N               = "length"
     val lengthCompare: N        = "lengthCompare"
+    val local: N                = "local"
     val longHash: N             = "longHash"
     val macroThis : N           = "_this"
     val macroContext : N        = "c"

compiler/src/dotty/tools/dotc/transform/DropBreaks.scala

@@ -0,0 +1,213 @@
+package dotty.tools
+package dotc
+package transform
+
+import ast.{Trees, tpd}
+import core.*
+import Decorators.*
+import NameKinds.BoundaryName
+import MegaPhase._
+import Types._, Contexts._, Flags._, DenotTransformers._
+import Symbols._, StdNames._, Trees._
+import util.Property
+import Flags.MethodOrLazy
+
+object DropBreaks:
+  val name: String = "dropBreaks"
+  val description: String = "replace local Break throws by labeled returns"
+
+  /** Usage data and other info associated with a Label symbol.
+   *  @param  goto     the return-label to use for a labeled return.
+   *  @param  enclMeth the enclosing method
+   */
+  class LabelUsage(val goto: TermSymbol, val enclMeth: Symbol):
+    /** The number of references to associated label that come from labeled returns */
+    var returnRefs: Int = 0
+    /** The number of other references to assocated label */
+    var otherRefs: Int = 0
+
+  private val LabelUsages = new Property.Key[Map[Symbol, LabelUsage]]
+  private val LabelsShadowedByTry = new Property.Key[Set[Symbol]]
+
+/** Rewrites local Break throws to labeled returns.
+ *  Drops `try` statements on breaks if no other uses of its label remain.
+ *  A Break throw with a `Label` created by some enclosing boundary is replaced
+ *  with a labeled return if
+ *
+ *    - the throw and the boundary are in the same method, and
+ *    - there is no try expression inside the boundary that encloses the throw.
+ */
+class DropBreaks extends MiniPhase:
+  import DropBreaks.*
+
+  import tpd._
+
+  override def phaseName: String = DropBreaks.name
+
+  override def description: String = DropBreaks.description
+
+  override def runsAfterGroupsOf: Set[String] = Set(ElimByName.name)
+    // we want by-name parameters to be converted to closures
+
+  private object LabelTry:
+
+    object GuardedThrow:
+
+      /** `(ex, local)` provided `expr` matches
+       *
+       *      if ex.label.eq(local) then ex.value else throw ex
+       */
+      def unapply(expr: Tree)(using Context): Option[(Symbol, Symbol)] = stripTyped(expr) match
+        case If(
+          Apply(Select(Select(ex: Ident, label), eq), (lbl @ Ident(local)) :: Nil),
+          Select(ex2: Ident, value),
+          Apply(throww, (ex3: Ident) :: Nil))
+        if label == nme.label && eq == nme.eq && local == nme.local && value == nme.value
+            && throww.symbol == defn.throwMethod
+            && ex.symbol == ex2.symbol && ex.symbol == ex3.symbol =>
+          Some((ex.symbol, lbl.symbol))
+        case _ =>
+          None
+    end GuardedThrow
+
+    /** `(local, body)` provided `tree` matches
+     *
+     *      try body
+     *      catch case ex: Break =>
+     *        if ex.label.eq(local) then ex.value else throw ex
+     */
+    def unapply(tree: Tree)(using Context): Option[(Symbol, Tree)] = stripTyped(tree) match
+      case Try(body, CaseDef(pat @ Bind(_, Typed(_, tpt)), EmptyTree, GuardedThrow(exc, local)) :: Nil, EmptyTree)
+      if tpt.tpe.isRef(defn.BreakClass) && exc == pat.symbol =>
+        Some((local, body))
+      case _ =>
+        None
+  end LabelTry
+
+  private object BreakBoundary:
+
+    /** `(local, body)` provided `tree` matches
+     *
+     *      { val local: Label[...] = ...; <LabelTry(local, body)> }
+     */
+    def unapply(tree: Tree)(using Context): Option[(Symbol, Tree)] = tree match
+      case Block((vd @ ValDef(nme.local, _, _)) :: Nil, LabelTry(caughtAndRhs))
+      if vd.symbol.info.isRef(defn.LabelClass) && vd.symbol == caughtAndRhs._1 =>
+        Some(caughtAndRhs)
+      case _ =>
+        None
+  end BreakBoundary
+
+  private object BreakThrow:
+
+    /** `(local, arg)` provided `tree` matches inlined
+     *
+     *    val Label_this: ... = local
+     *    throw new Break[...](Label_this, arg)
+     */
+    def unapply(tree: Tree)(using Context): Option[(Symbol, Tree)] = tree match
+      case Inlined(_,
+        (vd @ ValDef(label_this1, _, id: Ident)):: Nil,
+        Apply(throww, Apply(constr, Inlined(_, _, Ident(label_this2)) :: arg :: Nil) :: Nil))
+      if throww.symbol == defn.throwMethod
+          && label_this1 == nme.Label_this && label_this2 == nme.Label_this
+          && id.symbol.name == nme.local
+          && constr.symbol.isClassConstructor && constr.symbol.owner == defn.BreakClass =>
+        Some((id.symbol, arg))
+      case _ =>
+        None
+  end BreakThrow
+
+  /** The LabelUsage data associated with `lbl` in the current context */
+  private def labelUsage(lbl: Symbol)(using Context): Option[LabelUsage] =
+    for
+      usesMap <- ctx.property(LabelUsages)
+      uses <- usesMap.get(lbl)
+    yield
+      uses
+
+  /** If `tree` is a BreakBoundary, associate a fresh `LabelUsage` with its label. */
+  override def prepareForBlock(tree: Block)(using Context): Context = tree match
+    case BreakBoundary(label, _) =>
+      val mapSoFar = ctx.property(LabelUsages).getOrElse(Map.empty)
+      val goto = newSymbol(ctx.owner, BoundaryName.fresh(), Synthetic | Label, tree.tpe)
+      ctx.fresh.setProperty(LabelUsages,
+        mapSoFar.updated(label, LabelUsage(goto, ctx.owner.enclosingMethod)))
+    case _ =>
+      ctx
+
+  /** If `tree` is not a LabeledTry, include all enclosing labels in the
+   *  `LabelsShadowedByTry` context property. This means that breaks to these
+   *  labels will not be translated to labeled returns in the body of the try.
+   */
+  override def prepareForTry(tree: Try)(using Context): Context = tree match
+    case LabelTry(_, _) => ctx
+    case _ => ctx.property(LabelUsages) match
+      case Some(usesMap) =>
+        val setSoFar = ctx.property(LabelsShadowedByTry).getOrElse(Set.empty)
+        ctx.fresh.setProperty(LabelsShadowedByTry, setSoFar ++ usesMap.keysIterator)
+      case _ => ctx
+
+  /** If `tree` is a BreakBoundary, transform it as follows:
+   *   - Wrap it in a labeled block if its label has local uses
+   *   - Drop the try/catch if its label has no other uses
+   */
+  override def transformBlock(tree: Block)(using Context): Tree = tree match
+    case BreakBoundary(label, expr) =>
+      val uses = ctx.property(LabelUsages).get(label)
+      val tree1 =
+        if uses.otherRefs > 1 then
+          // one non-local ref is always in the catch clause; this one does not count
+          tree
+        else
+          expr
+      report.log(i"trans boundary block $label // ${uses.returnRefs}, ${uses.otherRefs}")
+      if uses.returnRefs > 0 then Labeled(uses.goto, tree1) else tree1
+    case _ =>
+      tree
+
+  /** Rewrite a BreakThrow
+   *
+   *     val Label_this: ... = local
+   *     throw new Break[...](Label_this, arg)
+   *
+   *  where `local` is defined in the current method and is not included in
+   *  LabeldShowedByTry to
+   *
+   *     return[target] arg
+   *
+   *  where `target` is the `goto` return label associated with `local`.
+   *  Adjust associated ref counts accordingly. The local refcount is increased
+   *  and the non-local refcount is decreased, since `local` the `Label_this`
+   *  binding containing `local` is dropped.
+   */
+  override def transformInlined(tree: Inlined)(using Context): Tree = tree match
+    case BreakThrow(lbl, arg) =>
+      report.log(i"trans inlined $arg, ${arg.source}, ${ctx.outer.source}, ${tree.source}")
+      labelUsage(lbl) match
+        case Some(uses: LabelUsage)
+        if uses.enclMeth == ctx.owner.enclosingMethod
+            && !ctx.property(LabelsShadowedByTry).getOrElse(Set.empty).contains(lbl)
+          =>
+          uses.otherRefs -= 1
+          uses.returnRefs += 1
+          cpy.Inlined(tree)(tree.call, Nil,
+            inContext(ctx.withSource(tree.expansion.source)) {
+              Return(arg, ref(uses.goto)).withSpan(arg.span)
+            })
+        case _ =>
+          tree
+    case _ =>
+      tree
+
+  /** If `tree` refers to an enclosing label, increase its non local recount.
+   *  This increase is corrected in `transformInlined` if the reference turns
+   *  out to be part of a BreakThrow to a local, non-shadowed label.
+   */
+  override def transformIdent(tree: Ident)(using Context): Tree =
+    if tree.symbol.name == nme.local then
+      for uses <- labelUsage(tree.symbol) do
+        uses.otherRefs += 1
+    tree
+
+end DropBreaks

library/src/scala/util/boundary.scala

@@ -0,0 +1,40 @@
+package scala.util
+import control.ControlException
+
+/** A boundary that can be exited by `break` calls.
+ *  `boundary` and `break` represent a unified and superior alternative for the
+ *  `scala.util.control.NonLocalReturns` and `scala.util.control.Breaks` APIs.
+ *  The main differences are:
+ *
+ *    - Unified names: `boundary` to establish a scope, `break` to leave it.
+ *      `break` can optionally return a value.
+ *    - Integration with exceptions. `break`s are logically non-fatal exceptions.
+ *      The `Break` exception class extends `ControlException` which is a regular
+ *      `RuntimeException`, optimized so that stack trace generation is suppressed.
+ *    - Better performance: breaks to enclosing scopes in the same method can
+ *      be rwritten to jumps.
+ */
+object boundary:
+
+  /** User code should call `break.apply` instead of throwing this exception
+   *  directly.
+   */
+  class Break[T](val label: Label[T], val value: T) extends ControlException
+
+  /** Labels are targets indicating which boundary will be exited by a `break`.
+   */
+  class Label[T]:
+    transparent inline def break(value: T): Nothing = throw Break(this, value)
+
+  /** Run `body` with freshly generated label as implicit argument. Catch any
+   *  breaks associated with that label and return their results instead of
+   *  `body`'s result.
+   */
+  transparent inline def apply[T <: R, R](inline body: Label[T] ?=> R): R =
+    val local = Label[T]()
+    try body(using local)
+    catch case ex: Break[T] @unchecked =>
+      if ex.label eq local then ex.value
+      else throw ex
+
+end boundary

library/src/scala/util/break.scala

@@ -0,0 +1,20 @@
+package scala.util
+
+/** This object has two apply methods that abort the current computation
+ *  up to an enclosing `boundary` call.
+ */
+object break:
+
+  /** Abort current computation and instead return `value` as the value of
+   *  the enclosing `boundary` call that created `label`.
+   */
+  transparent inline def apply[T](value: T)(using l: boundary.Label[T]): Nothing =
+    l.break(value)
+
+  /** Abort current computation and instead continue after the `boundary` call that
+   *  created `label`.
+   */
+  transparent inline def apply()(using l: boundary.Label[Unit]): Nothing =
+    apply(())
+
+end break

library/src/scala/util/control/ControlException.scala

@@ -0,0 +1,18 @@
+package scala.util.control
+
+/** A parent class for throwable objects intended for flow control.
+ *
+ *  Instances of ControlException don't record a stacktrace and are therefore
+ *  much more efficient to throw than normal exceptions.
+ *
+ *  Unlike `ControlThrowable`, `ControlException` is a regular `RuntimeException`
+ *  that is supposed to be handled like any other exception.
+ *
+ *  Instances of `ControlException` should not normally have a cause.
+ *  Legacy subclasses may set a cause using `initCause`.
+ */
+abstract class ControlException(message: String | Null) extends Throwable(
+  message, /*cause*/ null, /*enableSuppression=*/ false, /*writableStackTrace*/ false):
+
+  def this() = this(message = null)
+

tests/run/break-opt.check

@@ -0,0 +1,2 @@
+done
+done