Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -80,17 +80,17 @@ class Plan<T, E> {
body: () -> T throws E,
/// The task's name in traces and error reports.
name: string?,
/// The limits the task waits on. It starts once every one of them has
/// room, and holds none of them while it waits.
limits: Limit[],
/// The semaphores the task waits on. It starts once every one of them
/// has a free slot, and holds none of them while it waits.
semaphores: root.sync.Semaphore[],
/// Cancelling any of these tokens cancels the task.
cancel_tokens: CancelToken[],
/// Whether the task keeps running when its spawner is cancelled.
root: bool,

/// A plan that runs `body`, with nothing added to it.
function new(body: () -> T throws E, name: string? = null) -> Plan<T, E> throws never {
Plan { body: body, name: name, limits: [], cancel_tokens: [], root: false }
Plan { body: body, name: name, semaphores: [], cancel_tokens: [], root: false }
}

/// Returns this plan with a new body: `wrapper`, called with the old one.
Expand All @@ -110,7 +110,7 @@ class Plan<T, E> {
wrapper(body)
},
name: self.name,
limits: self.limits,
semaphores: self.semaphores,
cancel_tokens: self.cancel_tokens,
root: self.root,
}
Expand All @@ -129,52 +129,6 @@ class Plan<T, E> {
}
}

/// Caps how many tasks spawned `with` it run at once.
///
/// Tasks over the cap wait in line; the `spawn` still returns its `Future` at
/// once. A waiting task can be cancelled. A task spawned with several limits
/// starts once every one of them has room, and holds none of them while it
/// waits. Two spawns share a cap only if they use the same `Limit` value, and
/// a spawn that lists the same limit twice takes one slot.
///
/// # Examples
///
/// ```baml
/// let provider = baml.spawn.Limit.new(8);
/// let futures = ids.map((id) -> { spawn with provider { fetch(id) } });
/// ```
class Limit {
_handle: $rust_type,

/// Creates a limit that admits `capacity` tasks at a time.
///
/// # Throws
///
/// `InvalidArgument` if `capacity` is not positive.
//baml:mut_vm
function new(capacity: int) -> Limit throws root.errors.InvalidArgument {
$rust_function
}

/// How many tasks this limit admits at a time.
//baml:vm
function capacity(self) -> int throws never {
$rust_function
}

/// How many tasks hold a slot right now.
//baml:vm
function active_count(self) -> int throws never {
$rust_function
}

/// How many tasks are waiting for a slot right now.
//baml:vm
function queued_count(self) -> int throws never {
$rust_function
}
}

/// Spawns a task whose cancellation parent is the runtime, not the spawning
/// task: cancelling the spawner no longer cancels it.
///
Expand All @@ -187,12 +141,6 @@ class Root {
}
}

implements<T, E> Modifier<T, E> for Limit {
function apply(self, plan: Plan<T, E>) -> Plan<T, E> throws never {
Plan { ...plan, limits: plan.limits.concat([self]) }
}
}

implements<T, E> Modifier<T, E> for Root {
function apply(self, plan: Plan<T, E>) -> Plan<T, E> throws never {
Plan { ...plan, root: true }
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
//! Mutual exclusion between tasks that share an object.
//! Synchronization between tasks: `atomic` to guard an object's own state,
//! `Semaphore` to cap how many holders run at once.

/// Runs `fn` while holding `key`, and returns what it returns.
///
Expand Down Expand Up @@ -115,3 +116,156 @@ function _wait(ticket: $rust_type) -> null throws never {
function _exit(key: reflect.AnyClass | reflect.AnyClass[]) -> void throws never {
$rust_function
}

/// A pool of `capacity` slots: at most that many holders run at once.
///
/// A slot is taken by a task spawned `with` the semaphore, for the whole task,
/// or by `acquire` or `with` inside a running task. Holders over the cap wait
/// in line, in the order they arrived; a waiting holder can be cancelled.
///
/// Slots have no owner, so a holder never re-enters: every `acquire` or `with`
/// takes a slot of its own, and any task may release a permit. A `with` nested
/// inside another on the same semaphore (in one task, or in a task spawned
/// `with` it) takes a second slot, so once outer blocks hold every slot, every
/// inner one waits forever. A spawn with several semaphores starts once every
/// one has a free slot, and holds none of them while it waits; `with` calls
/// nested in each other take theirs one at a time.
///
/// # Examples
///
/// ```baml
/// function fetch_all(urls: string[]) -> string[] {
/// let provider = baml.sync.Semaphore.new(8); // at most 8 fetches at once
/// await baml.future.all(urls.map((url) -> {
/// spawn with provider { baml.http.fetch(url).text() }
/// }))
/// }
/// ```
class Semaphore {
_handle: $rust_type,

/// Creates a semaphore with `capacity` free slots.
///
/// # Throws
///
/// `InvalidArgument` if `capacity` is not positive.
//baml:mut_vm
function new(capacity: int) -> Semaphore throws root.errors.InvalidArgument {
$rust_function
}

/// How many slots this semaphore has.
//baml:vm
function capacity(self) -> int throws never {
$rust_function
}

/// How many slots are held right now.
//baml:vm
function active_count(self) -> int throws never {
$rust_function
}

/// How many holders are waiting for a slot right now.
//baml:vm
function queued_count(self) -> int throws never {
$rust_function
}

/// Waits for a free slot, and returns the permit that releases it.
///
/// Release it with `defer` right away, so every exit releases it:
///
/// ```baml
/// let permit = semaphore.acquire();
/// defer { permit.release() }
/// ```
///
/// Waiting is a cancellation checkpoint; taking a free slot is not. A task
/// cancelled while waiting holds no slot.
function acquire(self) -> Permit throws never {
let held = self._admit();
let acquired = false;
// Armed before the wait, so a wait that ends in cancellation leaves
// the queue, or gives back a slot that raced it.
defer {
if (!acquired) {
_release_permit(held)
}
}
if (!_admitted(held)) {
_wait_permit(held);
}
let permit = _permit(held);
acquired = true;
permit
}

/// Runs `fn` while holding a slot, and returns what it returns.
///
/// The slot is released however `fn` exits: returning, throwing, panicking
/// or being cancelled.
///
/// # Throws
///
/// Whatever `fn` throws, after releasing the slot.
function with<R, E>(self, fn: () -> R throws E) -> R throws E {
let held = self._admit();
defer { _release_permit(held) }
if (!_admitted(held)) {
_wait_permit(held);
}
fn()
}

/// (internal) Takes a free slot, or queues for one, and returns the hold.
//baml:mut_vm
function _admit(self) -> $rust_type throws never {
$rust_function
}
}

/// One slot of a [`Semaphore`], from `Semaphore.acquire`.
///
/// Any task may release it. A permit nobody can release any more (dropped
/// without `release`) gives its slot back when it is garbage collected, which
/// can be much later.
class Permit {
_handle: $rust_type,

/// Releases this slot. Releasing it again does nothing.
//baml:vm
function release(self) -> void throws never {
$rust_function
}
}

implements<T, E> root.spawn.Modifier<T, E> for Semaphore {
function apply(self, plan: root.spawn.Plan<T, E>) -> root.spawn.Plan<T, E> throws never {
root.spawn.Plan { ...plan, semaphores: plan.semaphores.concat([self]) }
}
}

/// (internal) Whether the hold from `Semaphore._admit` has its slot.
//baml:vm
function _admitted(held: $rust_type) -> bool throws never {
$rust_function
}

/// (internal) Waits until the hold from `Semaphore._admit` has its slot.
function _wait_permit(held: $rust_type) -> null throws never {
$rust_io_function
}

/// (internal) A permit for the hold from `Semaphore._admit`.
//baml:mut_vm
function _permit(held: $rust_type) -> Permit throws never {
$rust_function
}

/// (internal) Releases the hold from `Semaphore._admit`, or withdraws it from
/// the queue.
//baml:vm
function _release_permit(held: $rust_type) -> void throws never {
$rust_function
}
Original file line number Diff line number Diff line change
Expand Up @@ -235,9 +235,10 @@ function baml.sap.coerce <builtin>/baml/ns_sap/sap.baml
class baml.spawn.CancelToken <builtin>/baml/ns_spawn/spawn.baml:23
interface baml.spawn.Modifier <builtin>/baml/ns_spawn/spawn.baml:60
class baml.spawn.Plan <builtin>/baml/ns_spawn/spawn.baml:78
class baml.spawn.Limit <builtin>/baml/ns_spawn/spawn.baml:146
class baml.spawn.Root <builtin>/baml/ns_spawn/spawn.baml:183
function baml.sync.atomic <builtin>/baml/ns_sync/sync.baml:75
class baml.spawn.Root <builtin>/baml/ns_spawn/spawn.baml:137
function baml.sync.atomic <builtin>/baml/ns_sync/sync.baml:76
class baml.sync.Semaphore <builtin>/baml/ns_sync/sync.baml:144
class baml.sync.Permit <builtin>/baml/ns_sync/sync.baml:233
type baml.sys.ProcessInput <builtin>/baml/ns_sys/sys.baml:2
type baml.sys.Stdio <builtin>/baml/ns_sys/sys.baml:5
class baml.sys.ProcessOutput <builtin>/baml/ns_sys/sys.baml:23
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
function repro() -> int {
let g = baml.spawn.Limit.new(2);
let g = baml.sync.Semaphore.new(2);
let f = spawn with g {
42
};
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
source: crates/baml_fmt/tests/cases.rs
---
function repro() -> int {
let g = baml.spawn.Limit.new(2);
let g = baml.sync.Semaphore.new(2);
let f = spawn with g { 42 };
await f
}
2 changes: 1 addition & 1 deletion baml_language/crates/baml_query_btel/tests/engine.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1189,7 +1189,7 @@ async fn futures_record_when_they_were_scheduled_and_started() {
}

function main(n: int) -> int {
let one = baml.spawn.Limit.new(1);
let one = baml.sync.Semaphore.new(1);
let first = spawn with one { work(200) };
// Waits for `first` to finish.
let second = spawn with one { work(100) };
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -208,17 +208,17 @@ test "an_already_cancelled_task_never_starts" {
// goes to the next task.
function never_starts_admitted() -> string {
let log = StartLog { steps: [] };
let limit = baml.spawn.Limit.new(1) catch (e) {
let semaphore = baml.sync.Semaphore.new(1) catch (e) {
baml.errors.InvalidArgument => baml.sys.panic("positive")
};
let token = baml.spawn.CancelToken.new();
let _ = token.cancel();
let f = spawn with limit, token {
let f = spawn with semaphore, token {
log.steps.push("body");
1
};
let outcome = (await f) catch (e) { baml.panics.Cancelled => 0 };
let next = spawn with limit { 2 };
let next = spawn with semaphore { 2 };
`${outcome}:${log.steps.join(",")}:${await next}`
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -31,27 +31,27 @@ function fas_label(
}
}

// A one-slot limit and the task holding that slot for `hold_ms`: anything else
// spawned with the limit starts only once the holder is done (or cancelled).
// A one-slot semaphore and the task holding that slot for `hold_ms`: anything else
// spawned with the semaphore starts only once the holder is done (or cancelled).
class FasGate {
limit: baml.spawn.Limit,
semaphore: baml.sync.Semaphore,
holder: baml.future.Future<null, never>,
}

function fas_gate(hold_ms: int) -> FasGate {
let limit = baml.spawn.Limit.new(1) catch (e) {
let semaphore = baml.sync.Semaphore.new(1) catch (e) {
baml.errors.InvalidArgument => baml.sys.panic("one is positive"),
};
let holder = spawn with limit {
let holder = spawn with semaphore {
baml.sys.sleep(baml.time.Duration.from_milliseconds(hold_ms))
};
FasGate { limit: limit, holder: holder }
FasGate { semaphore: semaphore, holder: holder }
}

function fas_failure_preserves_successes() -> string {
let gate = fas_gate(100);
let failed = spawn { fas_value(-1) };
let later = spawn with gate.limit { fas_value(2) };
let later = spawn with gate.semaphore { fas_value(2) };
defer { gate.holder.cancel() }
let results = await baml.future.all_settled([failed, later, failed]);
if (!later.is_settled() || later.is_cancelled()) {
Expand All @@ -75,7 +75,7 @@ test "failure_preserves_successes_and_waits_for_later_inputs" {

function fas_failures_in_input_order() -> string {
let gate = fas_gate(100);
let first = spawn with gate.limit { fas_value(-1) };
let first = spawn with gate.semaphore { fas_value(-1) };
let second = spawn { fas_value(-2) };
defer { gate.holder.cancel() }
let results = await baml.future.all_settled([first, second]);
Expand All @@ -99,7 +99,7 @@ function fas_panic_and_cancellation() -> string {
// Cancelled while still queued behind the holder: its body never runs.
let gate = fas_gate(15000);
defer { gate.holder.cancel() }
let cancelled = spawn with gate.limit { fas_value(1) };
let cancelled = spawn with gate.semaphore { fas_value(1) };
cancelled.cancel();
let panic = spawn { fas_explode() };
let results = await baml.future.all_settled([panic, cancelled, spawn { fas_value(3) }]);
Expand Down Expand Up @@ -176,7 +176,7 @@ test "returning_an_error_value_is_still_success" {

function fas_cancel_collector_only() -> string {
let gate = fas_gate(15000);
let input = spawn with gate.limit { fas_value(7) };
let input = spawn with gate.semaphore { fas_value(7) };
defer { gate.holder.cancel() }
let collector = baml.future.all_settled([input]);
baml.sys.sleep(baml.time.Duration.from_milliseconds(100));
Expand Down Expand Up @@ -215,7 +215,7 @@ function fas_collector_cancelled_as_input_settles() -> string {
// The input reads `collectors[0]`, so it must not start before the push:
// its sleep alone does not order it after this task.
let gate = fas_gate(15000);
let input = spawn with gate.limit {
let input = spawn with gate.semaphore {
baml.sys.sleep(baml.time.Duration.from_milliseconds(20));
collectors[0].cancel();
fas_value(7)
Expand Down
Loading
Loading