@clayroach/effect 3.19.14-source-capture.8 → 3.19.14-source-trace.2

package/src/TReentrantLock.ts

@@ -0,0 +1,224 @@
+/**
+ * @since 2.0.0
+ */
+import type * as Effect from "./Effect.js"
+import * as internal from "./internal/stm/tReentrantLock.js"
+import type * as Scope from "./Scope.js"
+import type * as STM from "./STM.js"
+import type * as TRef from "./TRef.js"
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export const TReentrantLockTypeId: unique symbol = internal.TReentrantLockTypeId
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export type TReentrantLockTypeId = typeof TReentrantLockTypeId
+
+/**
+ * A `TReentrantLock` is a reentrant read/write lock. Multiple readers may all
+ * concurrently acquire read locks. Only one writer is allowed to acquire a
+ * write lock at any given time. Read locks may be upgraded into write locks. A
+ * fiber that has a write lock may acquire other write locks or read locks.
+ *
+ * The two primary methods of this structure are `readLock`, which acquires a
+ * read lock in a scoped context, and `writeLock`, which acquires a write lock
+ * in a scoped context.
+ *
+ * Although located in the STM package, there is no need for locks within STM
+ * transactions. However, this lock can be quite useful in effectful code, to
+ * provide consistent read/write access to mutable state; and being in STM
+ * allows this structure to be composed into more complicated concurrent
+ * structures that are consumed from effectful code.
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export interface TReentrantLock extends TReentrantLock.Proto {}
+/**
+ * @internal
+ * @since 2.0.0
+ */
+export interface TReentrantLock {
+  /** @internal */
+  readonly state: TRef.TRef<internal.LockState>
+}
+
+/**
+ * @since 2.0.0
+ */
+export declare namespace TReentrantLock {
+  /**
+   * @since 2.0.0
+   * @category models
+   */
+  export interface Proto {
+    readonly [TReentrantLockTypeId]: TReentrantLockTypeId
+  }
+}
+
+/**
+ * Acquires a read lock. The transaction will suspend until no other fiber is
+ * holding a write lock. Succeeds with the number of read locks held by this
+ * fiber.
+ *
+ * @since 2.0.0
+ * @category mutations
+ */
+export const acquireRead: (self: TReentrantLock) => STM.STM<number> = internal.acquireRead
+
+/**
+ * Acquires a write lock. The transaction will suspend until no other fibers
+ * are holding read or write locks. Succeeds with the number of write locks
+ * held by this fiber.
+ *
+ * @since 2.0.0
+ * @category mutations
+ */
+export const acquireWrite: (self: TReentrantLock) => STM.STM<number> = internal.acquireWrite
+
+/**
+ * Retrieves the number of acquired read locks for this fiber.
+ *
+ * @since 2.0.0
+ * @category mutations
+ */
+export const fiberReadLocks: (self: TReentrantLock) => STM.STM<number> = internal.fiberReadLocks
+
+/**
+ * Retrieves the number of acquired write locks for this fiber.
+ *
+ * @since 2.0.0
+ * @category mutations
+ */
+export const fiberWriteLocks: (self: TReentrantLock) => STM.STM<number> = internal.fiberWriteLocks
+
+/**
+ * Just a convenience method for applications that only need reentrant locks,
+ * without needing a distinction between readers / writers.
+ *
+ * See `TReentrantLock.writeLock`.
+ *
+ * @since 2.0.0
+ * @category mutations
+ */
+export const lock: (self: TReentrantLock) => Effect.Effect<number, never, Scope.Scope> = internal.lock
+
+/**
+ * Determines if any fiber has a read or write lock.
+ *
+ * @since 2.0.0
+ * @category mutations
+ */
+export const locked: (self: TReentrantLock) => STM.STM<boolean> = internal.locked
+
+/**
+ * Makes a new reentrant read/write lock.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const make: STM.STM<TReentrantLock> = internal.make
+
+/**
+ * Obtains a read lock in a scoped context.
+ *
+ * @since 2.0.0
+ * @category mutations
+ */
+export const readLock: (self: TReentrantLock) => Effect.Effect<number, never, Scope.Scope> = internal.readLock
+
+/**
+ * Retrieves the total number of acquired read locks.
+ *
+ * @since 2.0.0
+ * @category mutations
+ */
+export const readLocks: (self: TReentrantLock) => STM.STM<number> = internal.readLocks
+
+/**
+ * Determines if any fiber has a read lock.
+ *
+ * @since 2.0.0
+ * @category mutations
+ */
+export const readLocked: (self: TReentrantLock) => STM.STM<boolean> = internal.readLocked
+
+/**
+ * Releases a read lock held by this fiber. Succeeds with the outstanding
+ * number of read locks held by this fiber.
+ *
+ * @since 2.0.0
+ * @category mutations
+ */
+export const releaseRead: (self: TReentrantLock) => STM.STM<number> = internal.releaseRead
+
+/**
+ * Releases a write lock held by this fiber. Succeeds with the outstanding
+ * number of write locks held by this fiber.
+ *
+ * @since 2.0.0
+ * @category mutations
+ */
+export const releaseWrite: (self: TReentrantLock) => STM.STM<number> = internal.releaseWrite
+
+/**
+ * Runs the specified workflow with a lock.
+ *
+ * @since 2.0.0
+ * @category mutations
+ */
+export const withLock: {
+  (self: TReentrantLock): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  <A, E, R>(effect: Effect.Effect<A, E, R>, self: TReentrantLock): Effect.Effect<A, E, R>
+} = internal.withLock
+
+/**
+ * Runs the specified workflow with a read lock.
+ *
+ * @since 2.0.0
+ * @category mutations
+ */
+export const withReadLock: {
+  (self: TReentrantLock): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  <A, E, R>(effect: Effect.Effect<A, E, R>, self: TReentrantLock): Effect.Effect<A, E, R>
+} = internal.withReadLock
+
+/**
+ * Runs the specified workflow with a write lock.
+ *
+ * @since 2.0.0
+ * @category mutations
+ */
+export const withWriteLock: {
+  (self: TReentrantLock): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  <A, E, R>(effect: Effect.Effect<A, E, R>, self: TReentrantLock): Effect.Effect<A, E, R>
+} = internal.withWriteLock
+
+/**
+ * Obtains a write lock in a scoped context.
+ *
+ * @since 2.0.0
+ * @category mutations
+ */
+export const writeLock: (self: TReentrantLock) => Effect.Effect<number, never, Scope.Scope> = internal.writeLock
+
+/**
+ * Determines if a write lock is held by some fiber.
+ *
+ * @since 2.0.0
+ * @category mutations
+ */
+export const writeLocked: (self: TReentrantLock) => STM.STM<boolean> = internal.writeLocked
+
+/**
+ * Computes the number of write locks held by fibers.
+ *
+ * @since 2.0.0
+ * @category mutations
+ */
+export const writeLocks: (self: TReentrantLock) => STM.STM<number> = internal.writeLocks

package/src/TRef.ts

@@ -0,0 +1,178 @@
+/**
+ * @since 2.0.0
+ */
+
+import type * as Journal from "./internal/stm/journal.js"
+import * as internal from "./internal/stm/tRef.js"
+import type * as TxnId from "./internal/stm/txnId.js"
+import type * as Versioned from "./internal/stm/versioned.js"
+import type * as Option from "./Option.js"
+import type { Pipeable } from "./Pipeable.js"
+import type * as STM from "./STM.js"
+import type * as Types from "./Types.js"
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export const TRefTypeId: unique symbol = internal.TRefTypeId
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export type TRefTypeId = typeof TRefTypeId
+
+/**
+ * A `TRef<A>` is a purely functional description of a mutable reference that can
+ * be modified as part of a transactional effect. The fundamental operations of
+ * a `TRef` are `set` and `get`. `set` transactionally sets the reference to a
+ * new value. `get` gets the current value of the reference.
+ *
+ * NOTE: While `TRef<A>` provides the transactional equivalent of a mutable
+ * reference, the value inside the `TRef` should be immutable.
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export interface TRef<in out A> extends TRef.Variance<A>, Pipeable {
+  /**
+   * Note: the method is unbound, exposed only for potential extensions.
+   */
+  modify<B>(f: (a: A) => readonly [B, A]): STM.STM<B>
+}
+/**
+ * @internal
+ * @since 2.0.0
+ */
+export interface TRef<in out A> {
+  /** @internal */
+  todos: Map<TxnId.TxnId, Journal.Todo>
+  /** @internal */
+  versioned: Versioned.Versioned<A>
+}
+
+/**
+ * @since 2.0.0
+ */
+export declare namespace TRef {
+  /**
+   * @since 2.0.0
+   */
+  export interface Variance<in out A> {
+    readonly [TRefTypeId]: {
+      readonly _A: Types.Invariant<A>
+    }
+  }
+}
+
+/**
+ * @since 2.0.0
+ * @category mutations
+ */
+export const get: <A>(self: TRef<A>) => STM.STM<A> = internal.get
+
+/**
+ * @since 2.0.0
+ * @category mutations
+ */
+export const getAndSet: {
+  <A>(value: A): (self: TRef<A>) => STM.STM<A>
+  <A>(self: TRef<A>, value: A): STM.STM<A>
+} = internal.getAndSet
+
+/**
+ * @since 2.0.0
+ * @category mutations
+ */
+export const getAndUpdate: {
+  <A>(f: (a: A) => A): (self: TRef<A>) => STM.STM<A>
+  <A>(self: TRef<A>, f: (a: A) => A): STM.STM<A>
+} = internal.getAndUpdate
+
+/**
+ * @since 2.0.0
+ * @category mutations
+ */
+export const getAndUpdateSome: {
+  <A>(f: (a: A) => Option.Option<A>): (self: TRef<A>) => STM.STM<A>
+  <A>(self: TRef<A>, f: (a: A) => Option.Option<A>): STM.STM<A>
+} = internal.getAndUpdateSome
+
+/**
+ * @since 2.0.0
+ * @category constructors
+ */
+export const make: <A>(value: A) => STM.STM<TRef<A>> = internal.make
+
+/**
+ * @since 2.0.0
+ * @category mutations
+ */
+export const modify: {
+  <A, B>(f: (a: A) => readonly [B, A]): (self: TRef<A>) => STM.STM<B>
+  <A, B>(self: TRef<A>, f: (a: A) => readonly [B, A]): STM.STM<B>
+} = internal.modify
+
+/**
+ * @since 2.0.0
+ * @category mutations
+ */
+export const modifySome: {
+  <A, B>(fallback: B, f: (a: A) => Option.Option<readonly [B, A]>): (self: TRef<A>) => STM.STM<B>
+  <A, B>(self: TRef<A>, fallback: B, f: (a: A) => Option.Option<readonly [B, A]>): STM.STM<B>
+} = internal.modifySome
+
+/**
+ * @since 2.0.0
+ * @category mutations
+ */
+export const set: {
+  <A>(value: A): (self: TRef<A>) => STM.STM<void>
+  <A>(self: TRef<A>, value: A): STM.STM<void>
+} = internal.set
+
+/**
+ * @since 2.0.0
+ * @category mutations
+ */
+export const setAndGet: {
+  <A>(value: A): (self: TRef<A>) => STM.STM<A>
+  <A>(self: TRef<A>, value: A): STM.STM<A>
+} = internal.setAndGet
+
+/**
+ * @since 2.0.0
+ * @category mutations
+ */
+export const update: {
+  <A>(f: (a: A) => A): (self: TRef<A>) => STM.STM<void>
+  <A>(self: TRef<A>, f: (a: A) => A): STM.STM<void>
+} = internal.update
+
+/**
+ * @since 2.0.0
+ * @category mutations
+ */
+export const updateAndGet: {
+  <A>(f: (a: A) => A): (self: TRef<A>) => STM.STM<A>
+  <A>(self: TRef<A>, f: (a: A) => A): STM.STM<A>
+} = internal.updateAndGet
+
+/**
+ * @since 2.0.0
+ * @category mutations
+ */
+export const updateSome: {
+  <A>(f: (a: A) => Option.Option<A>): (self: TRef<A>) => STM.STM<void>
+  <A>(self: TRef<A>, f: (a: A) => Option.Option<A>): STM.STM<void>
+} = internal.updateSome
+
+/**
+ * @since 2.0.0
+ * @category mutations
+ */
+export const updateSomeAndGet: {
+  <A>(f: (a: A) => Option.Option<A>): (self: TRef<A>) => STM.STM<A>
+  <A>(self: TRef<A>, f: (a: A) => Option.Option<A>): STM.STM<A>
+} = internal.updateSomeAndGet

package/src/TSemaphore.ts

@@ -0,0 +1,129 @@
+/**
+ * @since 2.0.0
+ */
+
+import type * as Effect from "./Effect.js"
+import * as internal from "./internal/stm/tSemaphore.js"
+import type * as Scope from "./Scope.js"
+import type * as STM from "./STM.js"
+import type * as TRef from "./TRef.js"
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export const TSemaphoreTypeId: unique symbol = internal.TSemaphoreTypeId
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export type TSemaphoreTypeId = typeof TSemaphoreTypeId
+
+/**
+ * @since 2.0.0
+ * @category models
+ */
+export interface TSemaphore extends TSemaphore.Proto {}
+/**
+ * @internal
+ * @since 2.0.0
+ */
+export interface TSemaphore {
+  /** @internal */
+  readonly permits: TRef.TRef<number>
+}
+
+/**
+ * @since 2.0.0
+ */
+export declare namespace TSemaphore {
+  /**
+   * @since 2.0.0
+   * @category models
+   */
+  export interface Proto {
+    readonly [TSemaphoreTypeId]: TSemaphoreTypeId
+  }
+}
+
+/**
+ * @since 2.0.0
+ * @category mutations
+ */
+export const acquire: (self: TSemaphore) => STM.STM<void> = internal.acquire
+
+/**
+ * @since 2.0.0
+ * @category mutations
+ */
+export const acquireN: {
+  (n: number): (self: TSemaphore) => STM.STM<void>
+  (self: TSemaphore, n: number): STM.STM<void>
+} = internal.acquireN
+
+/**
+ * @since 2.0.0
+ * @category getters
+ */
+export const available: (self: TSemaphore) => STM.STM<number> = internal.available
+
+/**
+ * @since 2.0.0
+ * @category constructors
+ */
+export const make: (permits: number) => STM.STM<TSemaphore> = internal.make
+
+/**
+ * @since 2.0.0
+ * @category mutations
+ */
+export const release: (self: TSemaphore) => STM.STM<void> = internal.release
+
+/**
+ * @since 2.0.0
+ * @category mutations
+ */
+export const releaseN: {
+  (n: number): (self: TSemaphore) => STM.STM<void>
+  (self: TSemaphore, n: number): STM.STM<void>
+} = internal.releaseN
+
+/**
+ * @since 2.0.0
+ * @category mutations
+ */
+export const withPermit: {
+  (semaphore: TSemaphore): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  <A, E, R>(self: Effect.Effect<A, E, R>, semaphore: TSemaphore): Effect.Effect<A, E, R>
+} = internal.withPermit
+
+/**
+ * @since 2.0.0
+ * @category mutations
+ */
+export const withPermits: {
+  (semaphore: TSemaphore, permits: number): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  <A, E, R>(self: Effect.Effect<A, E, R>, semaphore: TSemaphore, permits: number): Effect.Effect<A, E, R>
+} = internal.withPermits
+
+/**
+ * @since 2.0.0
+ * @category mutations
+ */
+export const withPermitScoped: (self: TSemaphore) => Effect.Effect<void, never, Scope.Scope> = internal.withPermitScoped
+
+/**
+ * @since 2.0.0
+ * @category mutations
+ */
+export const withPermitsScoped: {
+  (permits: number): (self: TSemaphore) => Effect.Effect<void, never, Scope.Scope>
+  (self: TSemaphore, permits: number): Effect.Effect<void, never, Scope.Scope>
+} = internal.withPermitsScoped
+
+/**
+ * @since 2.0.0
+ * @category unsafe
+ */
+export const unsafeMake: (permits: number) => TSemaphore = internal.unsafeMakeSemaphore