Skip to content
Symi Docs
Rust

The Rust manual covers the recommended facade. The complete native crate is documented in the native Rust API reference.

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#

api::Session method

pub fn execution_mode(&self) -> ExecutionMode

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#

api::Session method

pub fn simplify_bulk(
    &self,
    targets: &[Expression],
) -> Result<Vec<BulkExpressionOutcome>, ApiError>

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#

api::Session method

pub fn generation(&self) -> u64
Calling forms and variants

api::Expression method: api::Expression::generation

pub fn generation(&self) -> u64

Variant using local assumptions — api::AssumptionScope method: api::AssumptionScope::generation

pub fn generation(&self) -> u64

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#

api::Expression method

pub fn session(&self) -> Session
Calling forms and variants

Variant using local assumptions — api::AssumptionScope method: api::AssumptionScope::session

pub fn session(&self) -> Session

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#

active_operations#

api::Session method

pub fn active_operations(&self) -> Vec<ActiveOperation>

Return the calls this session currently has running.

cancel_active_operations#

api::Session method

pub fn cancel_active_operations(&self) -> usize

Ask every running call of this session to stop, reporting how many were reached.

cancel_operation#

api::Session method

pub fn cancel_operation(&self, identifier: OperationIdentifier) -> bool

Ask one running call of this session to stop, reporting whether it was still running.

differentiate_bulk#

api::Session method

pub fn differentiate_bulk(
    &self,
    targets: &[Expression],
    variable: &Expression,
) -> Result<Vec<BulkExpressionOutcome>, ApiError>

Differentiate an ordered collection with one common symbol.

evaluate_numeric_bulk#

api::Session method

pub fn evaluate_numeric_bulk(
    &self,
    targets: &[Expression],
    options: NumericOptions,
) -> Result<Vec<BulkNumericOutcome>, ApiError>

Evaluate an ordered collection numerically under one captured configuration.

expand_bulk#

api::Session method

pub fn expand_bulk(
    &self,
    targets: &[Expression],
) -> Result<Vec<BulkExpressionOutcome>, ApiError>

Expand an ordered collection under one captured operation configuration.

extend#

api::Session method

pub fn extend<ReturnType>(
    &self,
    computation: impl FnOnce(LentContext<'_>) -> ReturnType,
) -> Result<ReturnType, ApiError>

Runs one embedder-supplied computation against this session's own context.

fast_recognisers_enabled#

api::Session method

pub fn fast_recognisers_enabled(&self) -> bool

Return whether later calls of this session may run the structural recognizers.

api::host_cancellation#

api module

pub mod host_cancellation;

The published control record an embedder writes to stop a call it cannot otherwise reach.

api::host_cancellation::host_cancellation_control_address#

api::host_cancellation re_export

pub use crate::operation::host_cancellation_control_address;

Public re_export placement for host_cancellation_control_address.

api::host_cancellation::host_cancellation_control_byte_length#

api::host_cancellation re_export

pub use crate::operation::host_cancellation_control_byte_length;

Public re_export placement for host_cancellation_control_byte_length.

api::host_cancellation::host_cancellation_requested#

api::host_cancellation re_export

pub use crate::operation::host_cancellation_requested;

Public re_export placement for host_cancellation_requested.

api::host_cancellation::host_cancellation_slot_count#

api::host_cancellation re_export

pub use crate::operation::host_cancellation_slot_count;

Public re_export placement for host_cancellation_slot_count.

api::host_cancellation::host_cancellation_slot_ticket#

api::host_cancellation re_export

pub use crate::operation::host_cancellation_slot_ticket;

Public re_export placement for host_cancellation_slot_ticket.

identity#

api::Session method

pub fn identity(&self) -> u64

Returns this session's stable identity for host object ownership checks.

initialize_parallelism#

api::Session method

pub fn initialize_parallelism(
    &self,
    worker_count: usize,
) -> Result<ParallelismInitialization, ApiError>

Initialize the one process-wide parallel backend with an explicit worker count.

new#

api::Session method

pub fn new() -> Self

Provides the new operation on this native type.

operation_context#

api::Session method

pub fn operation_context(&self) -> OperationContext

Return an operation carrying this session's published defaults.

operation_defaults#

api::Session method

pub fn operation_defaults(&self) -> Arc<OperationDefaults>

Return the execution policy this session publishes to the calls it starts.

api::options#

api module

pub mod options;

Binding-neutral option types accepted by the native API.

api::parallelism#

api module

pub mod parallelism;

Binding-neutral execution controls and ordered bulk result records.

parallelism_capability#

api::Session method

pub fn parallelism_capability(&self) -> ParallelismCapability

Return the target and session execution facts observed at this instant.

presentation_search_enabled#

api::Session method

pub fn presentation_search_enabled(&self) -> bool

Return whether later calls of this session may run the presentation search.

api::host_cancellation::release_host_cancellation_slot#

api::host_cancellation re_export

pub use crate::operation::release_host_cancellation_slot;

Public re_export placement for release_host_cancellation_slot.

api::host_cancellation::request_host_cancellation#

api::host_cancellation re_export

pub use crate::operation::request_host_cancellation;

Public re_export placement for request_host_cancellation.

api::host_cancellation::reserve_host_cancellation_slot#

api::host_cancellation re_export

pub use crate::operation::reserve_host_cancellation_slot;

Public re_export placement for reserve_host_cancellation_slot.

reset#

api::Session method

pub fn reset(&self) -> Result<(), ApiError>

Provides the reset operation on this native type.

serialize_bulk#

api::Session method

pub fn serialize_bulk(
    &self,
    targets: &[Expression],
) -> Result<Vec<BulkTextOutcome>, ApiError>

Serialize an ordered collection into canonical structural text.

set_execution_mode#

api::Session method

pub fn set_execution_mode(&self, execution_mode: ExecutionMode)

Change the execution mode used by later operations.

set_fast_recognisers_enabled#

api::Session method

pub fn set_fast_recognisers_enabled(&self, enabled: bool)

Select whether later calls of this session may run the structural recognizers.

set_operation_configuration#

api::Session method

pub fn set_operation_configuration(
    &self,
    configuration: OperationConfiguration,
)

Replace the configuration this session publishes to later calls.

set_operation_defaults#

api::Session method

pub fn set_operation_defaults(&self, defaults: OperationDefaults)

Replace the execution policy this session publishes to later calls.

set_presentation_search_enabled#

api::Session method

pub fn set_presentation_search_enabled(&self, enabled: bool)

Select whether later calls of this session may run the presentation search.

substitute_bulk#

api::Session method

pub fn substitute_bulk(
    &self,
    targets: &[Expression],
    variable: &Expression,
    value: &Expression,
) -> Result<Vec<BulkExpressionOutcome>, ApiError>

Substitute one common symbol and value throughout an ordered collection.

take_completed_operation_report#

api::Session method

pub fn take_completed_operation_report(
    &self,
) -> CompletedOperationReport

Take the diagnostic tail the completed calls of this session left behind.

take_operation_records#

api::Session method

pub fn take_operation_records(&self) -> Vec<OperationRecord>

Return the records the completed calls of this session emitted.

validate_assumption_proposition#

api::Session method

pub fn validate_assumption_proposition(
    &self,
    target: &AssumptionProposition,
) -> Result<(), ApiError>

Verifies that a host-held proposition belongs to this session and is still live.

validate_circle_2d_object#

api::Session method

pub fn validate_circle_2d_object(
    &self,
    target: &Circle2d,
) -> Result<(), ApiError>

Verifies that a host-held circle belongs to this session and is still live.

validate_cylindrical_algebraic_decomposition_object#

api::Session method

pub fn validate_cylindrical_algebraic_decomposition_object(
    &self,
    target: &CylindricalAlgebraicDecomposition,
) -> Result<(), ApiError>

Verifies that a host-held decomposition belongs to this session and is still live.

validate_expression#

api::Session method

pub fn validate_expression(
    &self,
    target: &Expression,
) -> Result<(), ApiError>

Verifies that a host-held expression belongs to this session and is still live.

validate_generation#

api::Session method

pub fn validate_generation(
    &self,
    generation: u64,
) -> Result<(), ApiError>

Verifies that an object generation is still live in this session.

validate_matrix_object#

api::Session method

pub fn validate_matrix_object(
    &self,
    target: &Matrix,
) -> Result<(), ApiError>

Verifies that a host-held matrix belongs to this session and is still live.

validate_point_2d_object#

api::Session method

pub fn validate_point_2d_object(
    &self,
    target: &Point2d,
) -> Result<(), ApiError>

Verifies that a host-held point belongs to this session and is still live.

validate_polygon_2d_object#

api::Session method

pub fn validate_polygon_2d_object(
    &self,
    target: &Polygon2d,
) -> Result<(), ApiError>

Verifies that a host-held polygon belongs to this session and is still live.

validate_segment_2d_object#

api::Session method

pub fn validate_segment_2d_object(
    &self,
    target: &Segment2d,
) -> Result<(), ApiError>

Verifies that a host-held segment belongs to this session and is still live.

validate_session_object#

api::Session method

pub fn validate_session_object(
    &self,
    generation: u64,
    object_session: &Session,
    object_generation: u64,
) -> Result<(), ApiError>

Verifies that a host object belongs to this session and is still live.

validate_triangle_2d_object#

api::Session method

pub fn validate_triangle_2d_object(
    &self,
    target: &Triangle2d,
) -> Result<(), ApiError>

Verifies that a host-held triangle belongs to this session and is still live.

validate_undefined_function_object#

api::Session method

pub fn validate_undefined_function_object(
    &self,
    target: &UndefinedFunction,
) -> Result<(), ApiError>

Verifies that a host-held undefined function belongs to this session and is still live.

ActiveOperation#

api re_export

pub use crate::operation::ActiveOperation;

Public re_export placement for ActiveOperation.

BulkExpressionOutcome#

api re_export

pub use parallelism::BulkExpressionOutcome;

One ordered result from an expression bulk operation.

Calling forms

Type: api::parallelism::BulkExpressionOutcome

pub enum BulkExpressionOutcome

BulkExpressionOutcome.diagnostic#

api::parallelism::BulkExpressionOutcome method

pub fn diagnostic(&self) -> Option<Diagnostic>

Return the item diagnostic, if the scalar operation did not produce a value.

BulkExpressionOutcome.index#

api::parallelism::BulkExpressionOutcome method

pub fn index(&self) -> usize

Return the original input position.

BulkExpressionOutcome.is_value#

api::parallelism::BulkExpressionOutcome method

pub fn is_value(&self) -> bool

Return whether this item contains a value.

BulkExpressionOutcome.value#

api::parallelism::BulkExpressionOutcome method

pub fn value(&self) -> Option<Expression>

Return the successful value, if this item succeeded.

BulkTextOutcome#

api re_export

pub use parallelism::BulkTextOutcome;

One ordered canonical-text result from an expression bulk operation.

Calling forms

Type: api::parallelism::BulkTextOutcome

pub enum BulkTextOutcome

BulkTextOutcome.diagnostic#

api::parallelism::BulkTextOutcome method

pub fn diagnostic(&self) -> Option<Diagnostic>

Return the item diagnostic, if serialization did not produce text.

BulkTextOutcome.index#

api::parallelism::BulkTextOutcome method

pub fn index(&self) -> usize

Return the original input position.

BulkTextOutcome.value#

api::parallelism::BulkTextOutcome method

pub fn value(&self) -> Option<String>

Return the serialized text, if this item succeeded.

CompletedOperationReport#

Type

pub struct CompletedOperationReport

What the completed calls of a session left behind for a caller to read.

CompletedOperationReport.cancelled_operation_count#

api::CompletedOperationReport field

pub cancelled_operation_count:

Counts the completed calls that were asked to stop before they returned.

CompletedOperationReport.consumed_work_units#

api::CompletedOperationReport field

pub consumed_work_units:

The deterministic work the completed calls charged.

CompletedOperationReport.operation_count#

api::CompletedOperationReport field

pub operation_count:

Counts the calls this report covers.

CompletedOperationReport.records#

api::CompletedOperationReport field

pub records:

The diagnostic records the completed calls emitted, in the order they emitted them.

ExecutionMode#

api re_export

pub use crate::operation::ExecutionMode;

Selects the execution policy used by one mathematical operation.

HOST_CANCELLATION_SLOT_COUNT#

api::host_cancellation re_export

pub use crate::operation::HOST_CANCELLATION_SLOT_COUNT;

Public re_export placement for HOST_CANCELLATION_SLOT_COUNT.

HostCancellationSlot#

api re_export

pub use host_cancellation::HostCancellationSlot;

Public re_export placement for HostCancellationSlot.

Calling forms

api::host_cancellation re_export: api::host_cancellation::HostCancellationSlot

pub use crate::operation::HostCancellationSlot;

LentContext#

Type

pub struct LentContext<'session>

The session's own context, lent to one embedder computation for the length of that call.

OperationConfiguration#

api re_export

pub use crate::operation::OperationConfiguration;

Immutable switches and resource defaults captured at operation entry.

OperationContext#

api re_export

pub use crate::operation::OperationContext;

Explicit state belonging to one public mathematical call.

OperationDefaults#

api re_export

pub use crate::operation::OperationDefaults;

The immutable execution policy a session publishes for the operations started under it.

OperationEvent#

api re_export

pub use crate::operation::OperationEvent;

What one compact record says, without the text that would describe it.

OperationIdentifier#

api re_export

pub use crate::operation::OperationIdentifier;

Public re_export placement for OperationIdentifier.

OperationRecord#

api re_export

pub use crate::operation::OperationRecord;

A structured operation-local record for diagnostics and instrumentation.

OperationStage#

api re_export

pub use crate::operation::OperationStage;

The stage a compact record was emitted from.

ParallelBackend#

api re_export

pub use parallelism::ParallelBackend;

Names the execution backend selected by the runtime.

Calling forms

Type: api::parallelism::ParallelBackend

pub enum ParallelBackend

ParallelBackend.RayonNative#

api::parallelism::ParallelBackend variant

RayonNative,

An owned native Rayon thread pool.

ParallelBackend.RayonWasm#

api::parallelism::ParallelBackend variant

RayonWasm,

A Rayon pool bootstrapped for atomic WebAssembly.

ParallelBackend.Sequential#

api::parallelism::ParallelBackend variant

Sequential,

The deterministic serial backend.

ParallelBackend.name#

api::parallelism::ParallelBackend method

pub fn name(self) -> &'static str

Return the stable lowercase backend spelling.

ParallelismCapability#

api re_export

pub use parallelism::ParallelismCapability;

Reports the parallel runtime facts observed at one instant.

Calling forms

Type: api::parallelism::ParallelismCapability

pub struct ParallelismCapability

ParallelismCapability.active#

api::parallelism::ParallelismCapability field

pub active:

Indicates that parallel work can currently be admitted.

ParallelismCapability.backend#

api::parallelism::ParallelismCapability field

pub backend:

Reports the backend selected by the target.

ParallelismCapability.compiled#

api::parallelism::ParallelismCapability field

pub compiled:

Indicates that this target contains a threaded backend.

ParallelismCapability.initialized#

api::parallelism::ParallelismCapability field

pub initialized:

Indicates that backend initialization has completed.

ParallelismCapability.is_parallel#

api::parallelism::ParallelismCapability method

pub fn is_parallel(&self) -> bool

Return whether this capability can admit parallel work.

ParallelismCapability.maximum_operation_concurrency#

api::parallelism::ParallelismCapability field

pub maximum_operation_concurrency:

Reports the largest task batch one operation may admit.

ParallelismCapability.selected_mode#

api::parallelism::ParallelismCapability field

pub selected_mode:

Reports the session mode captured for later operations.

ParallelismCapability.unavailable_reason#

api::parallelism::ParallelismCapability field

pub unavailable_reason:

Explains why parallel work is unavailable, when it is unavailable.

ParallelismCapability.worker_count#

api::parallelism::ParallelismCapability field

pub worker_count:

Reports the number of runtime workers.

ParallelismInitialization#

api re_export

pub use parallelism::ParallelismInitialization;

Reports the result of an explicit one-time runtime initialization request.

Calling forms

Type: api::parallelism::ParallelismInitialization

pub enum ParallelismInitialization

ParallelismInitialization.AlreadyInitialized#

api::parallelism::ParallelismInitialization variant

AlreadyInitialized,

The requested configuration matched the existing backend.

ParallelismInitialization.Initialized#

api::parallelism::ParallelismInitialization variant

Initialized,

This request created the process-wide backend.

ParallelismInitialization.name#

api::parallelism::ParallelismInitialization method

pub fn name(self) -> &'static str

Return the stable lowercase initialization spelling.

ParallelismUnavailableReason#

api re_export

pub use parallelism::ParallelismUnavailableReason;

Explains why a parallel backend is not active.

Calling forms

Type: api::parallelism::ParallelismUnavailableReason

pub enum ParallelismUnavailableReason

ParallelismUnavailableReason.CrossOriginIsolationUnavailable#

api::parallelism::ParallelismUnavailableReason variant

CrossOriginIsolationUnavailable,

Browser cross-origin isolation is unavailable.

ParallelismUnavailableReason.InitializationFailed#

api::parallelism::ParallelismUnavailableReason variant

InitializationFailed,

Backend initialization recorded a stable failure.

ParallelismUnavailableReason.NotCompiled#

api::parallelism::ParallelismUnavailableReason variant

NotCompiled,

The target was compiled without a parallel backend.

ParallelismUnavailableReason.NotInitialized#

api::parallelism::ParallelismUnavailableReason variant

NotInitialized,

A threaded backend exists but has not completed initialization.

ParallelismUnavailableReason.SharedMemoryUnavailable#

api::parallelism::ParallelismUnavailableReason variant

SharedMemoryUnavailable,

Shared WebAssembly memory is unavailable.

ParallelismUnavailableReason.SingleWorker#

api::parallelism::ParallelismUnavailableReason variant

SingleWorker,

The backend has only one worker.

ParallelismUnavailableReason.name#

api::parallelism::ParallelismUnavailableReason method

pub fn name(self) -> &'static str

Return the stable lowercase reason spelling.

SerialRouteReason#

api re_export

pub use crate::operation::SerialRouteReason;

Why an execution decision selected the serial route.