introduce Scope + ensureMap #1315

fwbrasil · 2025-07-02T00:23:57Z

This PR reworks resource-handling abstraction and improves safety of finalizer registration.

Change	Description
`Resource` to `Scope`	(`opaque type Scope <: Sync`) replacing `Resource`;
Finalizer registration	`ensureMap` avoids races by registering finalizers synchronously after acquisition.
Interrupt safety	Prevents interruption between acquisition and finalizer registration — not previously guaranteed.
`awaitClose` flag	Allows finalizers to run in background (no backpressure) or wait for completion.
`runLocally` method	Isolated execution without propagating outer finalizers; renamed from `runIsolated`.
*est additions	Adds hierarchical, interrupt, and isolation behavior tests for `Scope`.

Impact:

Safer, more flexible resource lifecycle management.
Cleaner semantics for nested and interruptible scopes.

fwbrasil · 2025-07-02T00:25:53Z

kyo-core/shared/src/main/scala/kyo/Scope.scala

+import kyo.Tag
+import kyo.kernel.ContextEffect
+
+opaque type Scope = Sync


This is planned to be the replacement for Resource. Instead of using ContextEffect, which has more strict type-level tracking, I'm using an opaque type + Local. The effect tracking is meant to ensure the Local is set in a scope to allow runFinalizer to dynamically check if there's an outer Scope finalizer. It's similar to how STM handles transactions.

fwbrasil · 2025-07-02T00:27:43Z

kyo-core/shared/src/main/scala/kyo/Scope.scala

+    def acquireRelease[A, S](acquire: => A < S)(release: A => Any < (Async & Abort[Throwable]))(using Frame): A < (Scope & S) =
+        withFinalizerUnsafe { finalizer =>
+            acquire.ensureMap { resource =>
+                val result = finalizer.ensure(_ => release(resource))


ensureMap avoids potential interruptions after acquire finishes. Paired with an unsafe finalizer.ensure, there's no possibility of interruption between the acquisition finishing and the finalizer callback being registered.

fwbrasil · 2025-07-02T00:28:51Z

kyo-core/shared/src/main/scala/kyo/Scope.scala

+            import AllowUnsafe.embrace.danger
+            val child = new Finalizer.Unsafe
+            parent.foreach(p => discard(p.ensure(child.close(_, closeParallelism))))
+            run(child, closeParallelism, awaitClose)(v(child))


@hearnadam does this cover the scenario you were exploring? The finalizer will be registered with the parent to ensure closing if the parent is closed

Actually, it shouldn't set the local so the resources are isolated. Updating

fwbrasil · 2025-07-02T00:30:36Z

kyo-core/shared/src/main/scala/kyo/Scope.scala

+            run(child, closeParallelism, awaitClose)(v(child))
+        }
+
+    private def run[A, S](finalizer: Finalizer, closeParallelism: Int, awaitClose: Boolean)(v: A < (Scope & S))(


awaitClose is a new feature and indicates if the execution should wait for the finalizer to close. If false, the closing happens in the background without backpressure. We could have separate apis returning a pending Sync instead of Async when it's false but it doesn't seem worth it.

fwbrasil · 2025-07-02T00:30:57Z

kyo-core/shared/src/test/scala/kyo/ScopeTest.scala

+        }
+    }
+
+    "can't be interrupted without registering the finalizer" in run {


this isn't supported by the current Resource

hearnadam · 2025-07-02T20:22:48Z

kyo-core/shared/src/main/scala/kyo/Scope.scala

+
+        type Callback = Maybe[Error[Any]] => Any < (Async & Abort[Throwable])
+
+        final class Unsafe(using frame: Frame, allow: AllowUnsafe):


minor: I would make the AllowUnsafe an inline given in the body.

I've added an import since it's simpler and I think it's equivalent to an inline given

hearnadam · 2025-07-08T00:52:00Z

kyo-core/shared/src/main/scala/kyo/Scope.scala

+        ensure(_ => v)
+
+    def ensure(callback: Maybe[Error[Any]] => Any < (Async & Abort[Throwable]))(using Frame): Unit < Scope =
+        withFinalizerUnsafe(f => Abort.get(f.ensure(callback)))


Is this not selecting the extension method on the safe variant? Can you use Finalizer.ensure(f)(callback)?

good catch, I've added f.unsafe.ensure to select the unsafe version since there's no need for an additional suspension

actually it isn't necessary. Unsafe is a class, not an opaque type so it's not ambiguous

hearnadam · 2025-07-08T00:53:49Z

kyo-core/shared/src/main/scala/kyo/Scope.scala

+                    Result.panic(new Closed(
+                        "Finalizer",
+                        frame,
+                        "This finalizer is already closed. This may happen if a background fiber escapes the scope of a 'Resource.run' call."


Suggested change

"This finalizer is already closed. This may happen if a background fiber escapes the scope of a 'Resource.run' call."

"This finalizer is already closed. This may happen if a background fiber escapes the scope of a 'Scope.run' call." 8000

hearnadam · 2025-07-08T00:54:33Z

kyo-core/shared/src/main/scala/kyo/Scope.scala

+                            Sync.Unsafe.evalOrThrow(
+                                Async.foreachDiscard(tasks, parallelism) { task =>
+                                    Abort.run[Throwable](task(ex))
+                                        .map(_.foldError(_ => (), ex => Log.error("Resource finalizer failed", ex.exception)))


Suggested change

.map(_.foldError(_ => (), ex => Log.error("Resource finalizer failed", ex.exception)))

.map(_.foldError(_ => (), ex => Log.error("Scope finalizer failed", ex.exception)))

hearnadam · 2025-07-08T00:55:39Z

kyo-core/shared/src/main/scala/kyo/Scope.scala

+    def runIsolated[A, S](f: Finalizer => A < (Scope & S))(using Frame): A < (Async & S) =
+        runIsolated(1)(f)
+
+    def runIsolated[A, S](closeParallelism: Int, awaitClose: Boolean = true)(f: Finalizer => A < (Scope & S))(


I don't think the name Isolated is helpful to me.

Perhaps runLocally?

ahoy-jon · 2025-07-09T06:53:35Z

kyo-core/shared/src/main/scala/kyo/Scope.scala

+      * @return
+      *   The acquired resource wrapped in Scope and S effects.
+      */
+    def acquireRelease[A, S](acquire: => A < S)(release: A => Any < (Async & Abort[Throwable]))(using Frame): A < (Scope & S) =


I would have used A < (Scope & S & Sync) instead of A < (Scope & S) 🤔

Ok, only for Kyo. acquireRelease!

ahoy-jon · 2025-07-09T07:01:57Z

kyo-core/shared/src/main/scala/kyo/Scope.scala

+  *   [[kyo.Scope.run]] For executing resource-managed computations
+  */
+opaque type Scope <: Sync = Sync
+


Suggested change

@deprecated("use `Scope`", "1.0-RC")

type Resource = Scope

@deprecated("use `Scope`", "1.0-RC")

val Resource = Scope

I think we could remove them after the 1.0

That's fine, but can you note that in the message?

fwbrasil · 2025-07-09T12:24:47Z

kyo-core/shared/src/test/scala/kyo/ScopeTest.scala

+        }
+    }
+
+    "hierarchical behavior" - {


new tests from here

hearnadam · 2025-07-09T12:20:06Z

kyo-core/shared/src/main/scala/kyo/Scope.scala

+  * @see
+  *   [[kyo.Scope.run]] For executing resource-managed computations
+  */
+opaque type Scope <: Sync = Sync


Will this result in Scope & Sync becoming Sync? I am not sure that's desirable for users.

no, just that Scope can subsume Sync. Sync can't subsume Scope

hearnadam · 2025-07-09T12:20:17Z

kyo-core/shared/src/main/scala/kyo/Scope.scala

+  *   [[kyo.Scope.run]] For executing resource-managed computations
+  */
+opaque type Scope <: Sync = Sync
+


That's fine, but can you note that in the message?

hearnadam · 2025-07-09T12:23:14Z

kyo-core/shared/src/main/scala/kyo/Scope.scala

+    private def withFinalizerUnsafe[A, S](f: AllowUnsafe ?=> Finalizer => A < S)(using Frame): A < (Scope & S) =
+        local.use {
+            case Present(finalizer) => f(using AllowUnsafe.embrace.danger)(finalizer)
+            case Absent             => bug("Missing finalizer from context")


I do wonder if this is the correct approach, but I suppose type level tracking is all that's needed.

this should never happen given the type-level tracking. STM does something similar

hearnadam · 2025-07-09T12:25:23Z

kyo-core/shared/src/main/scala/kyo/Scope.scala

+                                    .map(promise.safe.becomeDiscard)
+                            )
+
+            def await()(using AllowUnsafe): Fiber.Unsafe[Nothing, Unit] =


Maybe this should be fiber?

the unsafe apis normally return unsafe types?

hearnadam · 2025-07-09T12:35:30Z

kyo-core/shared/src/test/scala/kyo/ScopeTest.scala

+                escapedFiber <- Scope.run {
+                    for
+                        r <- Scope.acquire(resource)
+                        fiber <- Fiber.init {


I think this is a bit awkward (and pre-existing). I am not sure we should have closed as a result here, but see if we can just fire the finalizer immediately. Or forking should by default create a child scope that's closed when the parent is.

it's actually something I implemented (see Scope.internal.tryEnsure). If the outer scope is already closed, I don't see a reason to fail. For example some daemon fiber that forks others. Note that the scope always propagates

hearnadam · 2025-07-09T12:53:07Z

kyo-core/shared/src/main/scala/kyo/Scope.scala

+      * @return
+      *   The result of the effect wrapped in Async and S effects.
+      */
+    def runLocally[A, S](closeParallelism: Int, awaitClose: Boolean = true)(f: Finalizer => A < (Scope & S))(


I don't think this should handle Scope in it's current state - it doesn't set the Finalizer to Present, right?

hearnadam · 2025-07-09T12:54:04Z

kyo-core/shared/src/test/scala/kyo/ScopeTest.scala

+        }
+    }
+
+    "runLocally" - {


Can you add a test that stacks runLocally instances? I also think we need to use finalizer.ensure in some tests.

### Problem - We plan to add support for heirarchical Resource scopes (see: #1131), but the naming of `Resource` makes the behavior less clear. It seems much more intuitive to 'nest' scopes. ### Solution - Rename Resource to Scope. In #1315 Flavio will add a followup for local scoping.

fwbrasil commented Jul 2, 2025

View reviewed changes

fwbrasil commented Jul 2, 2025

View revie 8000 wed changes

fwbrasil commented Jul 2, 2025

View reviewed changes

fwbrasil added 2 commits July 1, 2025 22:42

introduce Scope + ensureMap

5687fa0

fix

20bd63f

fwbrasil force-pushed the map-ensure branch from b9d6b5e to 20bd63f Compare July 2, 2025 01:46

hearnadam reviewed Jul 8, 2025

View reviewed changes

fwbrasil added 5 commits July 8, 2025 22:10

Merge branch 'main' into map-ensure

da299b1

wip

d748b68

scope fixes + tests

359ff6b

migrate codebase to Scope

01f1dfc

review feedback

4ccffb0

fwbrasil marked this pull request as ready for review July 9, 2025 04:23

fwbrasil added 2 commits July 9, 2025 01:54

fix js build

49e03a6

fix interrupt test

36f8ddd

ahoy-jon reviewed Jul 9, 2025

View reviewed changes

fwbrasil commented Jul 9, 2025

View reviewed changes

kyo-core/shared/src/test/scala/kyo/ScopeTest.scala

}

}

"hierarchical behavior" - {

Copy link

Collaborator Author

fwbrasil Jul 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

new tests from here

hearnadam reviewed Jul 9, 2025

View reviewed changes

fwbrasil added 2 commits July 9, 2025 10:48

Merge branch 'main' into map-ensure

0f3103b

fixes

babc19d

hearnadam mentioned this pull request Jul 9, 2025

Rename: Resource -> Scope #1356

Merged

ahoy-jon marked this pull request as draft July 11, 2025 21:51

hearnadam force-pushed the map-ensure branch from aa6b127 to babc19d Compare July 16, 2025 03:52


		type Callback = Maybe[Error[Any]] => Any < (Async & Abort[Throwable])

		final class Unsafe(using frame: Frame, allow: AllowUnsafe):

	"This finalizer is already closed. This may happen if a background fiber escapes the scope of a 'Resource.run' call."
	"This finalizer is already closed. This may happen if a background fiber escapes the scope of a 'Scope.run' call." 8000

	.map(_.foldError(_ => (), ex => Log.error("Resource finalizer failed", ex.exception)))
	.map(_.foldError(_ => (), ex => Log.error("Scope finalizer failed", ex.exception)))

+@deprecated("use `Scope`", "1.0-RC")
+type Resource = Scope
+@deprecated("use `Scope`", "1.0-RC")
+val Resource = Scope

introduce Scope + ensureMap #1315

Are you sure you want to change the base?

introduce Scope + ensureMap #1315

Uh oh!

Conversation

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!