Crate wstp

source ·
Expand description

Bindings to the Wolfram Symbolic Transfer Protocol (WSTP).

This crate provides a set of safe and ergonomic bindings to the WSTP library, used to transfer Wolfram Language expressions between programs.

Quick Examples

Write an expression to a loopback Link, and then read it back from the same link object:

use wstp::Link;

let mut link = Link::new_loopback()?;

// Write the expression {"a", "b", "c"}
link.put_function("System`List", 3)?;
link.put_str("a")?;
link.put_str("b")?;
link.put_str("c")?;

// Read back the expression, concatenating the elements as we go:
let mut buffer = String::new();

for _ in 0 .. link.test_head("System`List")? {
    buffer.push_str(link.get_string_ref()?.as_str())
}

assert_eq!(buffer, "abc");

Transfer the expression "hello!" from one Link endpoint to another:

use std::thread;
use wstp::{Link, Protocol};

let mut link_a = Link::listen(Protocol::SharedMemory, "").unwrap();
let name = link_a.link_name();

// Start a background thread with the listen()'ing link.
let listening_thread = thread::spawn(move || {
    // This will block until connect() is called.
    link_a.activate().unwrap();

    link_a.put_str("hello!").unwrap();
});

// Connect to the listening link and read data from it.
let mut link_b = Link::connect(Protocol::SharedMemory, &name).unwrap();
assert_eq!(link_b.get_string().unwrap(), "hello!");

See also: channel()

What is WSTP?

The name Wolfram Symbolic Transfer Protocol (WSTP) refers to two interrelated things:

  • The WSTP protocol
  • The WSTP library, which provides the canonical implementation of the protocol via a C API.

The protocol

At a high level, the WSTP defines a full-duplex communication channel optimized for the transfer of Wolfram Language expressions between two endpoints. A WSTP connection typically has exactly two Link endpoints (loopback links are the only exception). A connection between two endpoints is established when one endpoint is created using Link::listen(), and another endpoint is created using Link::connect().

At a lower level, WSTP is actually three protocols:

which are represented by the Protocol enum. Each lower-level protocol is optimized for usage within a particular domain. For example, IntraProcess is the best link type to use when both Link endpoints reside within the same OS process, and TCPIP links can be used when the Link endpoints reside on different computers that are reachable across the network.

Given that the different Protocol types use different mechanisms to transfer data, it is not possible to create a connection between links of different types. E.g. a TCPIP type link cannot connect to a SharedMemory link, even if both endpoints were created on the same computer and in the same process.

The library

The WSTP library is distributed as part the Wolfram Language as both a static and dynamic library. The WSTP SDK is present in the file system layout of the Mathematica, Wolfram Desktop, and Wolfram Engine applications. The wstp crate is built on top of the WSTP C API.

When using the wstp crate as a dependency, the wstp crate’s cargo build script will use wolfram-app-discovery to automatically find any local installations of the Wolfram Language, and will link against the WSTP static library located within.

The Wolfram Engine can be downloaded and used for free for non-commercial or pre-production uses. A license must be purchased when used as part of a commercial or production-level product. See the Licensing and Terms of Use section in the Wolfram Engine FAQ for details.

Licensing

Usage of the WSTP library is subject to the terms of the MathLink License Agreement.

Re-exports

  • pub use crate::env::shutdown;

Modules

  • kernel
    Utilities for interacting with a Wolfram Kernel process via WSTP.
  • sys
    Raw bindings to the WSTP C API.

Structs

Enums

Functions

  • channel
    Create a full-duplex WSTP communication channel with two Link endpoints.