Rust bindings to the Wolfram Symbolic Transport Protocol (WSTP)

Related tags

Learning Resources rust wolfram-language rust-crate wstp
Overview

wstp

Bindings to the Wolfram Symbolic Transfer Protocol (WSTP) library.

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

Quick Examples

Loopback links

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()?.to_str())
    }

    assert_eq!(buffer, "abc");

    Ok(())
}

example();

Full-duplex links

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] (TODO) for details.

Related Links

Related crates

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

Related documentation

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.

Comments
  • polish: Remove redundant attrs on `unchecked_ref_cast_mut`

    polish: Remove redundant attrs on `unchecked_ref_cast_mut`

    • https://github.com/dtolnay/ref-cast/pull/38 fixes the unused_unsafe lint
    • https://github.com/dtolnay/ref-cast/pull/39 makes ref_cast_custom functions inline by default
    opened by dtolnay 1
  • bugfix: Replace reliance on `ref-cast` internals with `#[ref_cast_custom]`

    bugfix: Replace reliance on `ref-cast` internals with `#[ref_cast_custom]`

    This PR removes older code that worked around the inability to have private or unsafe ref-cast methods (ref-cast #9), and replaces it with the fancy new #[ref_cast_custom] macro introduced in ref-cast #35.

    opened by ConnorGray 0
  • featfix: Support building on Apple Silicon

    featfix: Support building on Apple Silicon

    Due to Cargo #8875, it is not currently possible to link to so-called "fat" libraries. However, in WL ~v12.3 and later, WSTP is distributed as a fat binary containing native code for for both x86_64 and arm64 targets.

    To work around this incompatibility, the macOS lipo command is used to generate a "thin" library, which cargo is able to successfully link against.

    opened by ConnorGray 0
  • feature: Compile-time generation of WSTP bindings

    feature: Compile-time generation of WSTP bindings

    Prior to this, wstp-sys has been using bindings to wstp.h that were pre-generated. This required using the generate-versioned-bindings.rs script to create a new file for each {<System ID>, <Wolfram Language version>} combination that wstp-sys wanted to support. This was fragile and time consuming, and inevitably always out of date.

    Using pre-generated bindings made some sense before wolfram-app-discovery was written, but it makes little sense now.

    There is a small compile-time tradeoff to doing this: the compile time of wstp-sys now includes the time needed to compile the new bindgen dependency, and the time to use bindgen to generate the WSTP Rust bindings file. However, the maintenance and "it actually works" benefits I think outweigh that consideration.

    I've left the pre-generated bindings files and code in place for now. At the very least, a minimal version of that logic is needed long-term so that wstp-sys can be built successfully in the docs.rs built environment (where we don't have access to a WSTP SDK to generate the bindings on the fly).

    It's possible it may make sense to enable usage of pre-generated bindings using a cargo feature. More experience with real-world usage is needed.

    opened by ConnorGray 0
  • feature: Add Expr::get_expr_with_resolver()

    feature: Add Expr::get_expr_with_resolver()

    This is an experimental feature intended to provide a workaround for the problem that the Wolfram Kernel does not always write symbol expressions with their complete context.

    For example, the symbol SystemList may be written as the string "List" and not "SystemList". That means that the context of "List" is ambiguous when being read off of the link by Link::get_expr().

    Link::get_expr_with_resolver() works around this problem by using a user-provided callback function to handle any ambiguous symbols. The user function can choose how to handle them. Doing this in a naive way (e.g. assuming every ambiguous symbol is in the System` context) is a hacky workaround, but sufficient for simple use-cases.

    A more robust method would be to ask the Kernel explicitly for the context, e.g. by evaluating Context["List"]. But that has performance considerations, and is not easy to do in the middle of get_expr().

    opened by ConnorGray 0
  • feature: Add more methods for putting/getting numeric types

    feature: Add more methods for putting/getting numeric types

    Also minor paper-cut improvements to the utility traits implemented by Protocol and Array, as well as an improvement to the error messages produced by Error::from_code(). See the commit log for more details.

    opened by ConnorGray 0
Owner
Wolfram Research, Inc.
Wolfram Research, Inc.
GitHub
Representing Wolfram Language expressions in Rust.

wolfram-expr Representation of Wolfram Language expressions. Examples Construct the expression {1, 2, 3}: use wolfram_expr::{Expr, Symbol}; let expr

Wolfram Research, Inc. 7 Aug 18, 2022
Symbolic EVM in Rust (WIP)

Ser Symbolic EVM in Rust Introduction Ser's design is informed by lessons I learned from a previous attempt to build a highly abstract & generalized s

Tannr 8 Jan 31, 2023
Rust lib for fetching official protoc (Protocol Buffer compiler) releases

protoc-fetcher Rust library for fetching official Protocol Buffer compiler (protoc) releases, pegged to a specific version. protoc-fetcher downloads a

Arcanyx Technical Wizardry LLC 2 Sep 5, 2022
Rust libraries for Bluesky's AT Protocol services. NOT STABLE (yet)

ATrium ATrium is a collection of Rust libraries designed to work with the AT Protocol, providing a versatile and coherent ecosystem for developers. Th

Yoshihiro Sugi 43 Jun 25, 2023
SDK for the Portfolio protocol written in rust.

portfolio-rs Minimalist toolkit for building rust applications on top of the portfolio protocol. Installation [Required] Foundry. Source. If not insta

Primitive 5 Aug 14, 2023
Precio is a Rust library that implements the Precio protocol for computing private layered histograms and sums.

Overview of Precio Precio is a Rust implementation of the protocol described in eprint.iacr.org/2021/1490. The goal of the protocol is to enable an an

Microsoft 9 Aug 16, 2023
Manas project aims to create a modular framework and ecosystem to create robust storage servers adhering to Solid protocol in rust.

मनस् | Manas Solid is a web native protocol to enable interoperable, read-write, collaborative, and decentralized web, truer to web's original vision.

Manomayam 17 Oct 5, 2023
Simple bit-level protocol definitions in Rust.

bin-proto Simple & fast structured bit-level binary co/dec in Rust. An improved and modernized fork of protocol. A more efficient but (slightly) less

null 16 Jun 13, 2024
A learning project/fun experiment in internet protocol

Piper a learning project/fun experiment in internet protocol Version 0.4.0 (SEMVER) Goals Piper is Simple. A page is a page. There are no secondary re

null 13 Oct 27, 2022
Simple and fast proxy checker that include protocol validation;

Open Proxies ⭐️ Leave me a start please ⭐️ it will motivate me to continue maintaining and adding futures About | Technologies | Requirements | Starti

kmoz000 3 Nov 29, 2022
Safe Rust bindings to the DynamoRIO dynamic binary instrumentation framework.

Introduction The dynamorio-rs crate provides safe Rust bindings to the DynamoRIO dynamic binary instrumentation framework, essentially allowing you to

S.J.R. van Schaik 17 Nov 21, 2022
alto provides idiomatic Rust bindings for OpenAL 1.1 and extensions (including EFX).

alto alto provides idiomatic Rust bindings for OpenAL 1.1 and extensions (including EFX). WARNING Because Alto interacts with global C state via dynam

null 80 Aug 7, 2022
Rust bindings to the dos-like framework

dos-like for Rust   This project provides access to Mattias Gustavsson's dos-like framework, so as to write DOS-like applications in Rust. How to use

Eduardo Pinho 9 Aug 25, 2022
Safe, idiomatic bindings to cFE and OSAL APIs for Rust

n2o4 The n2o4 crate provides safe, idiomatic Rust bindings to the APIs of cFE and OSAL, the libraries of the Core Flight System (cFS). IMPORTANT NOTE

null 3 Aug 29, 2022
Complete bindings to the raspicam C++ library

raspicam-rs Rust bindings to the amazing C++ raspicam library (with optional OpenCV utilities)! This is a followup to a Rust-based robotics project I

blusk 8 Oct 17, 2022
Leetcode Solutions in Rust, Advent of Code Solutions in Rust and more

RUST GYM Rust Solutions Leetcode Solutions in Rust AdventOfCode Solutions in Rust This project demostrates how to create Data Structures and to implem

Larry Fantasy 635 Jan 3, 2023
Simple autoclicker written in Rust, to learn the Rust language.

RClicker is an autoclicker written in Rust, written to learn more about the Rust programming language. RClicker was was written by me to learn more ab

null 7 Nov 15, 2022
Rust programs written entirely in Rust

mustang Programs written entirely in Rust Mustang is a system for building programs built entirely in Rust, meaning they do not depend on any part of

Dan Gohman 561 Dec 26, 2022
Rust 核心库和标准库的源码级中文翻译，可作为 IDE 工具的智能提示 (Rust core library and standard library translation. can be used as IntelliSense for IDE tools)

Rust 标准库中文版 这是翻译 Rust 库 的地方， 相关源代码来自于 https://github.com/rust-lang/rust。 如果您不会说英语，那么拥有使用中文的文档至关重要，即使您会说英语，使用母语也仍然能让您感到愉快。Rust 标准库是高质量的，不管是新手还是老手，都可以从中

wtklbm 493 Jan 4, 2023