Skip to content
Symi Docs
Swift
On this page

Context safety

A context owns its symbols, assumptions, interned expressions, and structural objects. Rust calls this owner a Session. Every returned expression, matrix, geometry object, undefined function, and CAD result records both owner identity and reset generation.

The public surfaces validate provenance before reading or mutating mathematical state:

  • direct operands must have the receiver's owner;
  • variable expressions must be same-owner symbols;
  • every nested collection member is checked;
  • matrices and geometry values retain their owner;
  • callable undefined functions validate every argument;
  • reset invalidates all earlier handles.

Mixing contexts raises context_mismatch. Using an object after reset_context() or Session::reset() raises stale_object. Symi never reinterprets a foreign symbol identifier through the receiving symbol table.

Default-context objects and objects from an explicit context also do not mix. Use one explicit context throughout an isolated computation. To transfer mathematics intentionally, serialize it and parse it in the destination context; assumptions are context state and must be established separately.

Releasing or freeing a JavaScript handle is also terminal for that handle. The recommended facade duplicates handles needed by raw iterable calls, so passing a value in an array does not unexpectedly free the caller's value.

execution_mode#

Not exposed by the Swift bindings. Available as Context.execution_mode in Python, api::Session::execution_mode in Rust.

Sessions expose sequential and automatic execution modes and start in sequential. Automatic mode permits the runtime to use its process-wide bounded backend; it does not promise a worker count. Initializing the backend does not by itself change how any session runs, so a caller wanting internal parallelism selects automatic as well. The mode is captured when an operation begins, so a mode change affects later operations only.

parallelism_capability() reports whether the target compiled a backend, whether it has been initialized, its pool worker count, the maximum concurrency one operation may use, and the stable reason for a serial fallback. Explicit contexts and their expressions remain the unit of ownership; the capability record is runtime metadata and is not part of a mathematical object or its serialization.

Native Python calls convert host values while the interpreter is attached, then detach it for pure Symi work before constructing Python results. An explicit Context and its immutable objects may therefore be shared by Python threads; module-level defaults remain thread-local. When a Python job system already provides outer worker threads, use sequential mode for those jobs or keep the outer worker count bounded so it does not multiply the internal Rayon workers. The automatic mode is a permission and does not promise a particular worker count.

init_thread_pool_with_capability#

The atomic browser package includes the canonical initThreadPool(worker_count) export from wasm-bindgen-rayon. Symi also exposes the generated initThreadPoolWithCapability(worker_count) adapter; call this adapter when using the Symi package so the runtime capability is published only after the shared Rayon workers are ready. Capability queries before that point report not_initialized and bulk operations use the serial implementation. A rejected bootstrap is recorded as initialization_failed and does not enable a fallback thread pool. The universal WASM package does not expose either thread bootstrap and reports not_compiled.

Kotlin and Swift calls retain the dedicated worker bridge for session and object ownership. Foreign calls through one mobile session are serialized at that bridge, while an operation running there may use the shared internal Rayon pool. Keep surrounding dispatch queues bounded and avoid adding a second per-operation worker pool; otherwise outer queue width and internal workers can oversubscribe the device.

simplify_bulk#

Not exposed by the Swift bindings. Available as Context.simplify_bulk in Python, api::Session::simplify_bulk in Rust.

The ordered bulk operations simplify_bulk, expand_bulk, differentiate_bulk, substitute_bulk, evaluate_numeric_bulk, and serialize_bulk validate every input against one context and generation before work begins. Results retain input order and use one captured operation configuration. A reset during the call rejects publication rather than returning a partially completed collection. An item-level decline or diagnostic does not reorder or cancel unrelated items.

generation#

Not exposed by the Swift bindings. Available as api::AssumptionScope::generation in Rust.

The generation objects currently produced by this context belong to. Resetting a context advances its generation, which is what makes every object made before the reset stale. The same accessor exists on the objects themselves, reporting the generation the object was created in; comparing the two is exactly what is_stale does.

session#

Not exposed by the Swift bindings. Available as api::AssumptionScope::session in Rust.

The context that owns this object. Every mathematical object belongs to one context for its whole life, and this accessor is how a host adapter carries the owner alongside the object. Objects from two different contexts cannot be combined; doing so is a context-mismatch error.

Symi documentation · Swift