concurrency

Concurrency primitives for coordinating work inside one Agency run. Use withLock to guard a shared resource so branches take turns instead of clobbering each other.

import { withLock } from "std::concurrency"

node main() {
  fork(range(5), shared: true) as _ {
    withLock("counter") as {
      // only one branch runs this block at a time
      updateSharedState()
    }
  }
}

Functions

withLock

withLock(
  name: string,
  timeoutMs: number | null = null,
  warnAfterMs: number | null = null,
  block: () -> any = null,
): any

Run a block while holding a named per-run mutex. Branches of the same run that use the same lock name execute this block one at a time. Branches using different names continue concurrently. The lock is released automatically when the block returns, throws, or unwinds for an interrupt.

@param name - Lock name; use stable names like "std::tty" for shared resources @param timeoutMs - Maximum time to wait before failing without acquiring the lock; null waits indefinitely @param warnAfterMs - Wait time before printing a diagnostic warning; defaults to 30s @param block - The work to run while holding the lock

Caller notes: - In subprocesses launched with std::agency.run(), the lock is coordinated by the parent process, so parent and child code share the same mutex. - Same-owner reentrancy on the same lock throws immediately. - Multi-lock deadlock cycles are not detected automatically; use timeoutMs when a bounded wait is required. - A fork branch may run inside a lock as long as it does not reacquire the same lock. Reacquiring the same lock from a fork spawned inside the lock can deadlock, because the outer scope waits for the fork while the branch waits for the outer lock to release.

Parameters:

Name	Type	Default
name	string
timeoutMs	number | null	null
warnAfterMs	number | null	null
block	() => any	null

Returns: any

(source)

concurrencyPool

concurrencyPool(size: number, items: any[], block: (item: any) -> any): any[]

Run a block in parallel across a bounded pool of workers.

@param size - Number of concurrent workers to run @param items - The items to process @param block - The work to run in each worker

Parameters:

Name	Type	Default
size	number
items	any[]
block	(item: any) => any

Returns: any[]

(source)