ScopedRef

Creates a new ScopedRef from an effect that acquires the initial value.

When to use

Use when creating a ScopedRef whose initial value requires acquiring resources that must be released.

See

• make for creating a ScopedRef from a value that does not require resource acquisition

declare const fromAcquire: <A, E, R>(acquire: Effect.Effect<A, E, R>) => Effect.Effect<ScopedRef<A>, E, Scope.Scope | R>

Creates a new ScopedRef from the specified value.

When to use

Use to create a ScopedRef when the initial value is already available or can be produced without acquiring resources.

Details

The evaluate function runs when the returned effect runs. The returned effect requires a Scope, and the reference closes the currently stored value's scope when that outer scope closes.

Gotchas

Do not use make for an initial value whose creation acquires resources; use fromAcquire so acquisition and finalization are tracked.

See

• fromAcquire for creating a ScopedRef from an effect that acquires the initial value
• set for replacing the current value with a newly acquired value

declare function make<A>(evaluate: LazyArg<A>): Effect<ScopedRef<A>, never, Scope>

Retrieves the current value of the scoped reference effectfully.

When to use

Use to read the value currently stored in a ScopedRef inside an Effect workflow.

See

• getUnsafe for reading the current value synchronously when an unsafe read is acceptable

declare function get<A>(self: ScopedRef<A>): Effect<A>

Retrieves the current value of the scoped reference synchronously.

When to use

Use when you need immediate synchronous access to the current ScopedRef value and can guarantee that reading outside the Effect API is safe.

See

• get for Effect-wrapped access in Effect programs

declare function getUnsafe<A>(self: ScopedRef<A>): A

A ScopedRef is a reference whose value is associated with resources, which must be released properly. You can both get the current value of any ScopedRef, as well as set it to a new value (which may require new resources). The reference itself takes care of properly releasing resources for the old value whenever a new value is obtained.

When to use

Use when an application needs to keep a current resource-backed value and later replace it with another acquired value while ensuring the previous value is released.

interface ScopedRef<in out A> extends Pipeable {
  readonly "~effect/ScopedRef": "~effect/ScopedRef";
  readonly backing: SynchronizedRef<readonly [Closeable, A]>;
}

Sets the value of this reference to a newly acquired scoped value, releasing any resources associated with the old value.

When to use

Use to replace the current value of an existing ScopedRef with a newly acquired scoped value while releasing resources for the previous value.

Details

This method will not return until either the reference is successfully changed to the new value, with old resources released, or until the attempt to acquire a new value fails.

declare const set: {
  <A, R, E>(acquire: Effect<A, E, R>): (self: ScopedRef<A>) => Effect<void, E, Exclude<R, Scope>>;
  <A, R, E>(self: ScopedRef<A>, acquire: Effect<A, E, R>): Effect<void, E, Exclude<R, Scope>>;
}