#wstp #wolfram #wolfram-language #wolfram-engine #mathlink

wstp

Bindings to the Wolfram Symbolic Transfer Protocol (WSTP)

8 releases

Uses new Rust 2021

0.2.4 Oct 20, 2022
0.2.3 Sep 19, 2022
0.2.2 May 18, 2022
0.2.1 Mar 4, 2022
0.1.4 Feb 19, 2022

#46 in FFI

Download history 8/week @ 2022-08-12 10/week @ 2022-08-19 14/week @ 2022-08-26 11/week @ 2022-09-02 15/week @ 2022-09-09 34/week @ 2022-09-16 12/week @ 2022-09-23 22/week @ 2022-09-30 19/week @ 2022-10-07 28/week @ 2022-10-14 17/week @ 2022-10-21 16/week @ 2022-10-28 14/week @ 2022-11-04 14/week @ 2022-11-11 19/week @ 2022-11-18 4/week @ 2022-11-25

53 downloads per month
Used in 2 crates

MIT/Apache

1.5MB
38K SLoC

wstp

Crates.io License Documentation

API Documentation | Changelog | Contributing

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;

fn example() -> Result<(), wstp::Error> {
    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");

    Ok(())
}

example();

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

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

// Start a background thread with a listen()'ing link.
let listening_thread = thread::spawn(|| {
    // This will block until an incoming connection is made.
    let mut link = Link::listen(Protocol::SharedMemory, "my-link").unwrap();

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

// Give the listening thread time to start before we
// try to connect to it.
thread::sleep(Duration::from_millis(20));

let mut link = Link::connect(Protocol::SharedMemory, "my-link").unwrap();
assert_eq!(link.get_string().unwrap(), "hello!");

See wolfram-library-link for examples of using WSTP links to transfer expressions to and from LibraryLink functions.

Building wstp

The wstp crate uses wolfram-app-discovery to locate a local installation of the Wolfram Language that contains a suitable copy of the WSTP SDK. If the WSTP SDK cannot be located, wstp will fail to build.

If you have installed the Wolfram Language to a location unknown to wolfram-app-discovery, you may specify the installed location manually by setting the WOLFRAM_APP_DISCOVERY environment variable. See Configuring wolfram-app-discovery for details.

  • wolfram-library-link — author libraries that can be dynamically loaded by the Wolfram Language
  • wolfram-expr — efficient and ergonomic representation of Wolfram expressions in Rust.
  • wolfram-app-discovery — utility for locating local installations of Wolfram applications and the Wolfram Language.

Developer Notes

See Development.md for instructions on how to perform common development tasks when contributing to the wstp crate.

See Maintenance.md for instructions on how to keep wstp up to date as new versions of the Wolfram Language are released.

License

Licensed under either of

at your option.

Note: Licensing of the WSTP library linked by the wstp crate is covered by the terms of the MathLink License Agreement.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

See CONTRIBUTING.md for more information.

Dependencies

~1.3–6MB
~113K SLoC