The Rust manual covers the recommended facade. The complete native crate is documented in the native Rust API reference.
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
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
Binding-neutral option types accepted by the native API.
api::parallelism#
api module
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
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
The deterministic work the completed calls charged.
CompletedOperationReport.operation_count#
api::CompletedOperationReport field
Counts the calls this report covers.
CompletedOperationReport.records#
api::CompletedOperationReport field
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
ParallelBackend.RayonNative#
api::parallelism::ParallelBackend variant
An owned native Rayon thread pool.
ParallelBackend.RayonWasm#
api::parallelism::ParallelBackend variant
A Rayon pool bootstrapped for atomic WebAssembly.
ParallelBackend.Sequential#
api::parallelism::ParallelBackend variant
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
Indicates that parallel work can currently be admitted.
ParallelismCapability.backend#
api::parallelism::ParallelismCapability field
Reports the backend selected by the target.
ParallelismCapability.compiled#
api::parallelism::ParallelismCapability field
Indicates that this target contains a threaded backend.
ParallelismCapability.initialized#
api::parallelism::ParallelismCapability field
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
Reports the session mode captured for later operations.
ParallelismCapability.unavailable_reason#
api::parallelism::ParallelismCapability field
Explains why parallel work is unavailable, when it is unavailable.
ParallelismCapability.worker_count#
api::parallelism::ParallelismCapability field
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
The requested configuration matched the existing backend.
ParallelismInitialization.Initialized#
api::parallelism::ParallelismInitialization variant
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
Backend initialization recorded a stable failure.
ParallelismUnavailableReason.NotCompiled#
api::parallelism::ParallelismUnavailableReason variant
The target was compiled without a parallel backend.
ParallelismUnavailableReason.NotInitialized#
api::parallelism::ParallelismUnavailableReason variant
A threaded backend exists but has not completed initialization.
ParallelismUnavailableReason.SharedMemoryUnavailable#
api::parallelism::ParallelismUnavailableReason variant
Shared WebAssembly memory is unavailable.
ParallelismUnavailableReason.SingleWorker#
api::parallelism::ParallelismUnavailableReason variant
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.