Skip to content
Symi Docs
WASM / JavaScript

Signatures in the WASM / JavaScript view are TypeScript. Where the JavaScript facade wraps an operation its form is listed first; the other calling forms are the raw wasm-bindgen exports.

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.

JavaScript
const first = new symi.Context();
const second = new symi.Context();
const x = first.symbol("x");
const y = second.symbol("y");

first.add(x, y);
first.resetContext();
x.add(1);

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 WASM / JavaScript 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 WASM / JavaScript 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 WASM / JavaScript 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 WASM / JavaScript 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.

Additional API#

differentiateBulk#

Raw WebAssembly: Default context

differentiateBulk(
    targets: Expression[],
    variable: Expression,
): BulkExpressionOutcome[]

Differentiate an ordered collection in the default context.

Calling forms

Raw WebAssembly: Explicit context: Context.differentiateBulk

differentiateBulk(
    targets: Expression[],
    variable: Expression,
): BulkExpressionOutcome[]

evaluateNumericBulk#

Raw WebAssembly: Default context

evaluateNumericBulk(
    targets: Expression[],
    significant_digits: number,
    accuracy: string,
    maximum_precision_bits: number,
    work_budget: number,
): BulkNumericOutcome[]

Evaluate an ordered collection numerically in the default context.

Calling forms

Raw WebAssembly: Explicit context: Context.evaluateNumericBulk

evaluateNumericBulk(
    targets: Expression[],
    significant_digits: number,
    accuracy: string,
    maximum_precision_bits: number,
    work_budget: number,
): BulkNumericOutcome[]

executionMode#

Raw WebAssembly: Default context

executionMode(): string

Return the execution mode of the default context.

Calling forms

Raw WebAssembly: Explicit context: Context.executionMode

executionMode(): string

expandBulk#

Raw WebAssembly: Default context

expandBulk(targets: Expression[]): BulkExpressionOutcome[]

Expand an ordered collection in the default context.

Calling forms

Raw WebAssembly: Explicit context: Context.expandBulk

expandBulk(targets: Expression[]): BulkExpressionOutcome[]

hostCancellationControlAddress#

Raw WebAssembly: Default context

hostCancellationControlAddress(): number

Return the address in linear memory of the control record an embedder writes to stop a call.

hostCancellationControlByteLength#

Raw WebAssembly: Default context

hostCancellationControlByteLength(): number

Return how many bytes of linear memory the host cancellation control record occupies.

hostCancellationRequested#

Raw WebAssembly: Default context

hostCancellationRequested(slot_index: number, ticket: number): boolean

Return whether a stop request stands against one control-record reservation.

hostCancellationSlotCount#

Raw WebAssembly: Default context

hostCancellationSlotCount(): number

Return how many reservations the host cancellation control record holds.

hostCancellationSlotTicket#

Raw WebAssembly: Default context

hostCancellationSlotTicket(slot_index: number): number

Return the ticket a reserved control-record slot answers to, or zero when it is not reserved.

initThreadPoolWithCapability#

Raw WebAssembly: Default context

initThreadPoolWithCapability(worker_count: number): Promise

Start the shared WebAssembly Rayon pool and publish its capability after startup succeeds.

initializeParallelism#

Raw WebAssembly: Default context

initializeParallelism(worker_count: number): string

Initialize parallel execution for the default context.

Calling forms

Raw WebAssembly: Explicit context: Context.initializeParallelism

initializeParallelism(worker_count: number): string

parallelismCapability#

Raw WebAssembly: Default context

parallelismCapability(): ParallelismCapability

Return the parallel execution capability of the default context.

Calling forms

Raw WebAssembly: Explicit context: Context.parallelismCapability

parallelismCapability(): ParallelismCapability

releaseHostCancellationSlot#

Raw WebAssembly: Default context

releaseHostCancellationSlot(slot_index: number, ticket: number): void

Release one control-record reservation and clear any stop request standing against it.

reserveHostCancellationSlot#

Raw WebAssembly: Default context

reserveHostCancellationSlot(): number

Reserve one control-record slot for the calls this thread starts next, or -1 when none is free.

serializeBulk#

Raw WebAssembly: Default context

serializeBulk(targets: Expression[]): BulkTextOutcome[]

Serialize an ordered collection in the default context.

Calling forms

Raw WebAssembly: Explicit context: Context.serializeBulk

serializeBulk(targets: Expression[]): BulkTextOutcome[]

setExecutionMode#

Raw WebAssembly: Default context

setExecutionMode(name: string): void

Select the execution mode of the default context.

Calling forms

Raw WebAssembly: Explicit context: Context.setExecutionMode

setExecutionMode(name: string): void

simplifyBulk#

Raw WebAssembly: Default context

simplifyBulk(targets: Expression[]): BulkExpressionOutcome[]

Simplify an ordered collection in the default context.

Calling forms

Raw WebAssembly: Explicit context: Context.simplifyBulk

simplifyBulk(targets: Expression[]): BulkExpressionOutcome[]

substituteBulk#

Raw WebAssembly: Default context

substituteBulk(
    targets: Expression[],
    variable: Expression,
    value: Expression,
): BulkExpressionOutcome[]

Substitute throughout an ordered collection in the default context.

Calling forms

Raw WebAssembly: Explicit context: Context.substituteBulk

substituteBulk(
    targets: Expression[],
    variable: Expression,
    value: Expression,
): BulkExpressionOutcome[]

BulkExpressionOutcome#

BulkExpressionOutcome.diagnostic#

Raw WebAssembly: BulkExpressionOutcome property

readonly diagnostic: string | undefined

Return the item diagnostic when the operation declined or failed.

BulkExpressionOutcome.index#

Raw WebAssembly: BulkExpressionOutcome property

readonly index: number

Return the original input position of this outcome.

BulkExpressionOutcome.value#

Raw WebAssembly: BulkExpressionOutcome property

readonly value: Expression | undefined

Return the expression value when the item succeeded.

BulkTextOutcome#

BulkTextOutcome.diagnostic#

Raw WebAssembly: BulkTextOutcome property

readonly diagnostic: string | undefined

Return the item diagnostic when the operation declined or failed.

BulkTextOutcome.index#

Raw WebAssembly: BulkTextOutcome property

readonly index: number

Return the original input position of this outcome.

BulkTextOutcome.value#

Raw WebAssembly: BulkTextOutcome property

readonly value: string | undefined

Return the canonical text when the item succeeded.

ParallelismCapability#

ParallelismCapability.active#

Raw WebAssembly: ParallelismCapability property

readonly active: boolean

Whether the selected backend can currently execute parallel work.

ParallelismCapability.backend#

Raw WebAssembly: ParallelismCapability property

readonly backend: string

Return the backend selected for this target.

ParallelismCapability.compiled#

Raw WebAssembly: ParallelismCapability property

readonly compiled: boolean

Whether this target was compiled with a parallel backend.

ParallelismCapability.initialized#

Raw WebAssembly: ParallelismCapability property

readonly initialized: boolean

Whether the process-wide parallel backend has been initialized.

ParallelismCapability.maximumOperationConcurrency#

Raw WebAssembly: ParallelismCapability property

readonly maximumOperationConcurrency: number

Return the largest task batch one operation may admit.

ParallelismCapability.selectedMode#

Raw WebAssembly: ParallelismCapability property

readonly selectedMode: string

Return the execution mode selected for later operations.

ParallelismCapability.unavailableReason#

Raw WebAssembly: ParallelismCapability property

readonly unavailableReason: string | undefined

Return the stable reason parallel execution is unavailable, if any.

ParallelismCapability.workerCount#

Raw WebAssembly: ParallelismCapability property

readonly workerCount: number

Return the configured worker count.

Symi documentation · WASM / JavaScript