Scope

zio.blocks.scope.Scope

See theScope companion object

sealed abstract class Scope extends Finalizer

A scope that manages resource lifecycle with compile-time verified safety.

==Closed-scope safety==

The operations allocate, open, and $ throw java.lang.IllegalStateException if called on a scope that has already closed. The exception message explains what went wrong and how to fix it. This prevents silent use-after-free bugs where a scope reference escapes its scoped { } block and a resource is accessed after its finalizers have run.

defer on a closed scope is silently ignored (no-op), and scoped on a closed scope creates a born-closed child.

Attributes

Companion: object
Source: Scope.scala
Graph
Supertypes: trait Finalizer

class Object

trait Matchable

class Any
Known subtypes: class Child[P]

object global
Self type: Scope

Members list

Type members

Classlikes

Enrichment for bare Resource[A] values.

Provides .allocate as syntax sugar for scope.allocate(resource), enabling uniform resource.allocate syntax whether the resource is raw or scoped.

Type parameters

A: the resource value type

Attributes

Source: Scope.scala
Supertypes: class Object

trait Matchable

class Any

Enrichment for $[Resource[A]] scoped values.

Provides allocate for acquiring a resource that is itself scoped. The Resource never leaves the scope wrapper; only its result becomes scoped.

Type parameters

A: the underlying resource value type

Attributes

Source: Scope.scala
Supertypes: class Object

trait Matchable

class Any

Types

Opaque scoped-value wrapper, unique to each scope instance.

Different scopes have structurally incompatible $ types, which prevents accidentally mixing values from one scope with operations on another at compile time. Erased to A at runtime (zero-cost).

Type parameters

A: the underlying value type

Attributes

Source: Scope.scala

The parent scope type in the scope hierarchy.

For Scope.global, this is global.type (self-referential). For child scopes, this is the concrete type of the enclosing scope. Used by lower to safely widen parent-scoped values into this scope.

Attributes

Source: Scope.scala

Value members

Abstract methods

Returns whether the current thread owns this scope.

Ownership is checked to detect cross-thread scope usage. Always returns true for Scope.global and for scopes created with open() (which are ''unowned''). For scopes created via scoped, returns true only on the thread that entered the scoped block.

Attributes

Returns: true if the calling thread is the owner of this scope
Source: Scope.scala

Concrete methods

Acquires a resource in this scope, registering its finalizer.

The resource's make method is called to produce a value and register any cleanup actions with this scope's finalizer registry. If this scope is already closed, no acquisition occurs and a default-valued $[A] is returned.

Type parameters

A: the resource value type

Value parameters

resource: the Resource describing how to acquire and release the value

Attributes

Returns: the acquired value wrapped as $[A]
Throws: java.lang.IllegalStateException
if this scope is already closed
Source: Scope.scala

Convenience overload that acquires an AutoCloseable value directly.

Equivalent to allocate(Resource(value)); the value's close() method is registered as a finalizer.

Type parameters

A: the AutoCloseable subtype

Value parameters

value: a by-name expression producing the AutoCloseable value

Attributes

Returns: the acquired value wrapped as $[A]
Throws: java.lang.IllegalStateException
if this scope is already closed
Source: Scope.scala

Registers a finalizer to run when this scope closes.

Finalizers are executed in LIFO order when the scope closes. If the scope is already closed, the finalizer is silently ignored and a no-op DeferHandle is returned.

Value parameters

f: the cleanup action to run on scope closure

Attributes

Returns: a DeferHandle that can be used to cancel the registration, or a no-op handle if the scope is already closed
Definition Classes: Finalizer
Source: Scope.scala

Thread-safe check for whether this scope has been closed.

Once a scope is closed its finalizers have already run. Subsequent calls to $, allocate, or open will throw java.lang.IllegalStateException. Scope.global returns false until JVM shutdown.

Attributes

Returns: true if this scope's finalizers have already been executed
Source: Scope.scala

Lowers a parent-scoped value into this scope.

This is safe because a parent scope always outlives its children: the child's finalizers run before the parent closes. The operation is zero-cost at runtime (a cast).

Type parameters

A: the underlying value type

Value parameters

value: a value scoped to this scope's parent

Attributes

Returns: the same value, re-tagged with this scope's identity
Source: Scope.scala

Creates a child scope that must be explicitly closed.

The returned Scope.OpenScope contains the child scope and a close() function. The child's finalizers are linked to this (parent) scope so that if the parent closes first, the child's finalizers also run. Calling close() on the Scope.OpenScope detaches the child from the parent, runs its finalizers, and returns a Finalization.

Attributes

Returns: a scoped Scope.OpenScope wrapping the new child
Throws: java.lang.IllegalStateException
if this scope is already closed
Source: Scope.scala

Inherited methods

Macro-enforced access to five scoped values simultaneously (N=5).

All five parameters are subject to the same receiver-only constraint as the N=1 and N=2 overloads. See (sa: $[A])(f: A => B) for the full safety rules.

Type parameters

A1: the underlying type of the first scoped value
A2: the underlying type of the second scoped value
A3: the underlying type of the third scoped value
A4: the underlying type of the fourth scoped value
A5: the underlying type of the fifth scoped value
B: the result type produced by the lambda

Value parameters

f: a lambda whose parameters are only used as method receivers
sa1: the first scoped value to access
sa2: the second scoped value to access
sa3: the third scoped value to access
sa4: the fourth scoped value to access
sa5: the fifth scoped value to access

Attributes

Returns: the result as B if B has an Unscoped instance, otherwise as $[B]
Throws: java.lang.IllegalStateException
if this scope is already closed
Inherited from:: ScopeVersionSpecific (hidden)
Source: ScopeVersionSpecific.scala

Macro-enforced access to four scoped values simultaneously (N=4).

All four parameters are subject to the same receiver-only constraint as the N=1 and N=2 overloads. See (sa: $[A])(f: A => B) for the full safety rules.

Type parameters

A1: the underlying type of the first scoped value
A2: the underlying type of the second scoped value
A3: the underlying type of the third scoped value
A4: the underlying type of the fourth scoped value
B: the result type produced by the lambda

Value parameters

f: a lambda whose parameters are only used as method receivers
sa1: the first scoped value to access
sa2: the second scoped value to access
sa3: the third scoped value to access
sa4: the fourth scoped value to access

Attributes

Returns: the result as B if B has an Unscoped instance, otherwise as $[B]
Throws: java.lang.IllegalStateException
if this scope is already closed
Inherited from:: ScopeVersionSpecific (hidden)
Source: ScopeVersionSpecific.scala

Macro-enforced access to three scoped values simultaneously (N=3).

All three parameters are subject to the same receiver-only constraint as the N=1 and N=2 overloads. See (sa: $[A])(f: A => B) for the full safety rules.

Type parameters

A1: the underlying type of the first scoped value
A2: the underlying type of the second scoped value
A3: the underlying type of the third scoped value
B: the result type produced by the lambda

Value parameters

f: a lambda whose parameters are only used as method receivers
sa1: the first scoped value to access
sa2: the second scoped value to access
sa3: the third scoped value to access

Attributes

Returns: the result as B if B has an Unscoped instance, otherwise as $[B]
Throws: java.lang.IllegalStateException
if this scope is already closed
Inherited from:: ScopeVersionSpecific (hidden)
Source: ScopeVersionSpecific.scala

Macro-enforced access to two scoped values simultaneously (N=2).

Both scoped values are unwrapped and the lambda is applied. The lambda may call methods on either parameter, and may feed the result of one as an argument to a method of the other (e.g., d1.method(d2.result())). Direct passing of either parameter as a bare argument is rejected at compile time.

Attributes

Throws

java.lang.IllegalStateException

if this scope is already closed

Example

 $(db, cache)((d, c) => d.query(c.key()))
 $(db, cache)((d, c) => d.query("x") + c.get("y"))

Inherited from:

ScopeVersionSpecific (hidden)

Source

ScopeVersionSpecific.scala

Macro-enforced access to a scoped value (N=1).

Unwraps the scoped value, applies the function, and returns the result. If B has an Unscoped instance, the result is returned directly as B (auto-unwrapped). Otherwise, the result is re-wrapped as $[B]. The macro verifies at compile time that the lambda parameter is only used in method-receiver position (e.g., x.method()), preventing resource leaks through capture, storage, or passing as an argument.

Type parameters

A: the input value type
B: the output value type

Value parameters

f: a lambda whose parameter is only used as a method receiver
sa: the scoped value to access

Attributes

Returns

the result as B if B has an Unscoped instance (auto-unwrapped), otherwise as $[B]

Throws

java.lang.IllegalStateException

if this scope is already closed

Example

 // Allowed:
 (scope $ db)(_.query("SELECT 1"))
 (scope $ db)(db => db.query("a") + db.query("b"))
 // Rejected at compile time:
 (scope $ db)(db => store(db))       // param as argument
 (scope $ db)(db => () => db.query()) // captured in closure

Inherited from:

ScopeVersionSpecific (hidden)

Source

ScopeVersionSpecific.scala

Escape hatch: unwrap a scoped value to its raw type, bypassing compile-time scope safety. Emits a compiler warning.

Use this only for interop with code that cannot work with scoped types. If the type is pure data, prefer adding an Unscoped instance instead.

Type parameters

A: the underlying type of the scoped value

Value parameters

sa: the scoped value to unwrap

Attributes

Returns: the raw value of type A, no longer tracked by the scope
Inherited from:: ScopeVersionSpecific (hidden)
Source: ScopeVersionSpecific.scala

Create a child scope. The block receives a child scope and returns a plain value of type A, which must have an Unscoped instance.

Type parameters

A: the return type of the scoped block; must have an Unscoped instance, ensuring only pure data escapes the scope boundary

Value parameters

f: a function that receives a Scope.Child and returns a value of type A

Attributes

Returns

the value of type A, after all child-scope finalizers have run

Throws

java.lang.IllegalStateException

if the current thread does not own this scope (thread-ownership violation)

Example

 Scope.global.scoped { scope =>
   import scope._
   val db: $[Database] = allocate(Resource(new Database))
   (scope $ db)(_.query("SELECT 1"))
 }

Inherited from:

ScopeVersionSpecific (hidden)

Source

ScopeVersionSpecific.scala

Abstract fields

Reference to the parent scope in the hierarchy.

Scope.global is self-referential (parent == this). For child scopes, this points to the scope that created this one. The parent always outlives its children, which is what makes lower safe.

Attributes

Source: Scope.scala

Implicits

Enrichment for bare Resource[A] values.

Provides .allocate as syntax sugar for scope.allocate(resource), enabling uniform resource.allocate syntax whether the resource is raw or scoped.

Type parameters

A: the resource value type

Attributes

Source: Scope.scala

Enrichment for $[Resource[A]] scoped values.

Provides allocate for acquiring a resource that is itself scoped. The Resource never leaves the scope wrapper; only its result becomes scoped.

Type parameters

A: the underlying resource value type

Attributes

Source: Scope.scala

Inherited implicits

Attributes

Inherited from:: ScopeVersionSpecific (hidden)
Source: ScopeVersionSpecific.scala

In this article