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
1 change: 1 addition & 0 deletions baml_language/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 6 additions & 0 deletions baml_language/crates/baml_base/src/qualified_name.rs
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,12 @@ pub const BAML_STD_PREFIX: &str = "baml.";
/// recursion for output-format rendering, SAP streaming, and Python codegen.
pub const BAML_JSON_JSON: &str = "baml.json.json";

/// FQN of the sys-op a `baml.sync.atomic` call parks on when another task
/// holds the lock. Exempt from the `$init` io check (E0163): `$init` runs one
/// VM at a time with no other task alive, so no lock it meets is ever held by
/// someone else and the wait never runs there.
pub const BAML_SYNC_WAIT: &str = "baml.sync._wait";

/// Canonical host-facing typed AI stream. Compiler synthesis, engine handle
/// lifting, and SDK generators must share this identity rather than carrying
/// independent string literals.
Expand Down
117 changes: 117 additions & 0 deletions baml_language/crates/baml_builtins2/baml_std/baml/ns_sync/sync.baml
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
//! Mutual exclusion between tasks that share an object.

/// Runs `fn` while holding `key`, and returns what it returns.
///
/// Only one task at a time runs an `atomic` block on a given key; others
/// calling `atomic` with the same key wait their turn, in the order they
/// arrived. Blocks on different keys never wait for each other. A task already
/// inside an `atomic` block on a key (one nested in another, however many calls
/// apart) enters again without waiting, and the key is released when the
/// outermost block exits. A spawned task is a different task: it does not share
/// its spawner's hold.
///
/// Only other `atomic` blocks on the same key are excluded; code that reads or
/// writes the object outside such a block is not protected. Objects reachable
/// from `key` are not locked with it.
///
/// A key is a class instance, compared by identity: every reference to one
/// object is the same key, and two objects with equal fields are different
/// keys. A value that passes through a host SDK comes back as a copy, which is
/// a new object and so a new key.
///
/// A list holds every instance in it together. The block waits, holding none
/// of them, until it can take all of them at once, so blocks naming the same
/// objects in different orders take turns instead of deadlocking. Instances
/// the task already holds are re-entered at once and stay held while it waits
/// for the rest. The list is copied on entry: changing it inside `fn` does not
/// change what is held.
///
/// `fn` runs once, in the calling task. The key is released however `fn` exits:
/// returning, throwing, panicking or being cancelled. Writes `fn` made before
/// exiting are kept, not rolled back. Waiting for the key is a cancellation
/// checkpoint; taking a free key, or re-entering a held one, is not. The key
/// stays held while `fn` awaits or does I/O.
///
/// # Parameters
///
/// - `key`: the object to hold, or a list of objects to hold together.
/// A typed list like `Account[]` passes as
/// `accounts.map((a) -> reflect.AnyClass { a })`.
/// - `fn`: what to run while holding it.
///
/// # Returns
///
/// What `fn` returns.
///
/// # Throws
///
/// Whatever `fn` throws, after releasing the key.
///
/// # Examples
///
/// ```baml
/// class Account {
/// balance: int,
///
/// function deposit(self, amount: int) -> void {
/// baml.sync.atomic(self, () -> void {
/// self.balance += amount;
/// })
/// }
/// }
///
/// // Two transfers in opposite directions take turns.
/// function transfer(from: Account, to: Account, amount: int) -> bool {
/// baml.sync.atomic([from, to], () -> bool {
/// if (from.balance < amount) {
/// return false;
/// }
/// from.deposit(-amount); // this task holds `from`: enters at once
/// to.deposit(amount);
/// true
/// })
/// }
/// ```
function atomic<R, E>(
key: reflect.AnyClass | reflect.AnyClass[],
fn: () -> R throws E,
) -> R throws E {
let held = _held(key);
let ticket = _enter(held);
// Armed before the wait, so a wait that ends in cancellation still runs
// it; `_exit` releases only keys this task holds.
defer { _exit(held) }
if (ticket != null) {
_wait(ticket);
}
fn()
}

/// (internal) `key` itself, or a copy of a list key: what the block holds,
/// whatever `fn` does to the list.
//baml:mut_vm
//baml:fallible
function _held<K>(key: K) -> K throws never {
$rust_function
}

/// (internal) Takes `key`'s objects, or re-enters those this task holds;
/// returns null. When another task holds any of the rest, queues this one and
/// returns its place in line.
//baml:mut_vm
//baml:fallible
function _enter(key: reflect.AnyClass | reflect.AnyClass[]) -> $rust_type? throws never {
$rust_function
}

/// (internal) Waits until the keys queued for by `_enter` are this task's.
function _wait(ticket: $rust_type) -> null throws never {
$rust_io_function
}

/// (internal) Undoes one `_enter` of `key` by this task.
//baml:mut_vm
//baml:fallible
function _exit(key: reflect.AnyClass | reflect.AnyClass[]) -> void throws never {
$rust_function
}
1 change: 1 addition & 0 deletions baml_language/crates/baml_builtins2/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -214,6 +214,7 @@ pub const ALL: &[BuiltinFile] = &[
builtin!("baml", "ns_iter/iter.baml"),
builtin!("baml", "ns_future/future.baml"),
builtin!("baml", "ns_spawn/spawn.baml"),
builtin!("baml", "ns_sync/sync.baml"),
builtin!("baml", "ns_host/host.baml"),
builtin!("baml", "ns_time/duration.baml"),
builtin!("baml", "ns_time/instant.baml"),
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -237,6 +237,7 @@ interface baml.spawn.Modifier <builtin>/baml/ns_spawn/spawn.
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
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
6 changes: 4 additions & 2 deletions baml_language/crates/baml_compiler2_hir_ty/src/init_io.rs
Original file line number Diff line number Diff line change
Expand Up @@ -260,15 +260,17 @@ pub(crate) fn resolved_function<'db>(
}

/// The fully-qualified name of `func` when it is an io sysop
/// (`$rust_io_function`), else `None`.
/// (`$rust_io_function`), else `None`. `baml.sync._wait` never runs in `$init`
/// (see [`baml_base::qualified_name::BAML_SYNC_WAIT`]), so it is not one here.
fn io_sysop_of<'db>(
db: &'db dyn baml_compiler2_hir::Db,
viewer: baml_base::SourceRoot,
func: FunctionLoc<'db>,
) -> Option<Name> {
let body = baml_compiler2_hir::body::function_body(db, func);
match body.as_ref() {
FunctionBody::Builtin(BuiltinKind::Io) => Some(qualified_name(db, viewer, func)),
FunctionBody::Builtin(BuiltinKind::Io) => Some(qualified_name(db, viewer, func))
.filter(|name| name.as_str() != baml_base::qualified_name::BAML_SYNC_WAIT),
_ => None,
}
}
Expand Down
48 changes: 46 additions & 2 deletions baml_language/crates/baml_ide/src/symbol_pool.rs
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,16 @@ fn split_companion(name: &str) -> Option<(&str, &str)> {
Some((&name[..pos], &name[pos + 1..]))
}

/// `baml.sync` has no host surface: its functions and methods are not part of
/// generated SDKs, and its classes cross only as opaque handles. Every host
/// call is its own task, so a key `atomic` held for it would be released as
/// the call returned, and a host callback run inside `atomic` could deadlock
/// re-entering BAML for the same key.
fn host_has_no_operations(pkg: &baml_type::Package, ns_path: &[Name]) -> bool {
matches!(pkg, baml_type::Package::Dep(label) if label.as_str() == "baml")
&& matches!(ns_path, [ns] if ns.as_str() == "sync")
}

/// Only the spec and stream callable companions are part of generated host
/// SDKs. The remaining companions stay available inside BAML through their
/// ordinary `@...` function symbols.
Expand Down Expand Up @@ -231,7 +241,9 @@ pub fn build_symbol_pool(db: &ProjectDatabase, viewer: SourceRoot) -> SymbolPool
continue;
}

if hide_from_host_sdk(method.name.as_str()) {
if hide_from_host_sdk(method.name.as_str())
|| host_has_no_operations(&pkg, &ns_path)
{
continue;
}

Expand Down Expand Up @@ -466,7 +478,7 @@ pub fn build_symbol_pool(db: &ProjectDatabase, viewer: SourceRoot) -> SymbolPool
continue;
}

if hide_from_host_sdk(func.name.as_str()) {
if hide_from_host_sdk(func.name.as_str()) || host_has_no_operations(&pkg, &ns_path) {
continue;
}

Expand Down Expand Up @@ -868,6 +880,38 @@ mod tests {
}
}

/// Nothing in `baml.sync` is callable from a host SDK, and its classes
/// reach hosts as opaque handles with no methods.
#[test]
fn sync_has_no_host_operations() {
let root = Path::new("/tmp/sync_host_surface");
let mut db = ProjectDatabase::new();
db.workspace(root);
db.file(
root.join("main.baml").as_path(),
"class Counter {\n n int\n}\n",
);

let pool = build_symbol_pool(&db, db.workspace_root().unwrap());
let in_sync = |name: &cg::Name| {
name.package().as_str() == "baml"
&& name.namespace().iter().map(Name::as_str).eq(["sync"])
};
for (name, symbol) in &pool {
if !in_sync(name) {
continue;
}
match symbol {
cg::Symbol::Class(class) => assert!(
class.static_methods.is_empty() && class.instance_methods.is_empty(),
"{name} must reach hosts without methods",
),
cg::Symbol::Function(_) => panic!("{name} must not reach hosts"),
_ => {}
}
}
}

/// The unit type reaches generators as `Null` however it is spelled, so a
/// generator's "returns nothing" form agrees with the checker's shorthand
/// rules: through an alias, a redundant union, or an uninhabited member.
Expand Down
Loading
Loading