Struct wstp::Link

#[repr(transparent)]
pub struct Link { /* private fields */ }

WSTP link endpoint.

WSClose() is called on the underlying WSLINK when Drop::drop() is called for a value of this type.

WSTP C API Documentation: WSLINK

Wolfram Language Documentation: LinkObject

Implementations

impl Link

pub fn wait(&mut self) -> Result<(), Error>

WSTP C API Documentation: WSWaitForLinkActivity

pub fn wait_with_callback<F>(&mut self, callback: F) -> Result<bool, Error>where
    F: FnMut(&mut Link) -> ControlFlow<()> + Send + Sync,

Wait for data to become available, periodically calling a callback.

true will be returned if data is available. false will be returned if the callback returns Break.

Example

use wstp::{Link, Protocol};

let mut listener = Link::listen(Protocol::IntraProcess, "").unwrap();

let mut counter = 0;

listener
    .wait_with_callback(|_: &mut Link| {
        use std::ops::ControlFlow;

        counter += 1;

        if counter < 5 {
            ControlFlow::Continue(())
        } else {
            ControlFlow::Break(())
        }
    })
    .unwrap();

User data fields

This function will temporarily replace any user data values (set using Link::set_user_data) which are associated with the current link. The user data values on the &mut Link parameter inside the callback are an implementation detail of this function and must not be modified.

WSTP C API Documentation: WSWaitForLinkActivityWithCallback

impl Link

pub fn get_type(&self) -> Result<TokenType, Error>

Get the type of the next token available to read on this link.

See also Link::get_token().

pub fn get_token(&mut self) -> Result<Token<'_>, Error>

Read the next token from this link.

See also Link::get_type().

Example

Read the expression {5, "second", foo} from a link one Token at a time:

use wstp::{Link, Token};

// Put {5, "second", foo}
let mut link = Link::new_loopback().unwrap();
link.put_function("System`List", 3).unwrap();
link.put_i64(5).unwrap();
link.put_str("second").unwrap();
link.put_symbol("Global`foo").unwrap();

// Read it back
assert!(matches!(link.get_token().unwrap(), Token::Function { length: 3 }));
assert!(matches!(link.get_token().unwrap(), Token::Symbol(s) if s.as_str() == "System`List"));
assert!(matches!(link.get_token().unwrap(), Token::Integer(5)));
assert!(matches!(link.get_token().unwrap(), Token::String(s) if s.as_str() == "second"));
assert!(matches!(link.get_token().unwrap(), Token::Symbol(s) if s.as_str() == "Global`foo"));

pub fn get_raw_type(&self) -> Result<i32, Error>

Get the raw type of the next token available to read on this link.

If the returned type is WSTKERR, an error is returned.

See also Link::get_type().

WSTP C API Documentation: WSGetType()

pub fn get_string_ref<'link>(
    &'link mut self
) -> Result<LinkStr<'link, str>, Error>

WSTP C API Documentation: WSGetUTF8String()

pub fn get_string(&mut self) -> Result<String, Error>

Convenience wrapper around Link::get_string_ref().

pub fn get_symbol_ref<'link>(
    &'link mut self
) -> Result<LinkStr<'link, str>, Error>

WSTP C API Documentation: WSGetUTF8Symbol()

pub fn get_utf8_str<'link>(
    &'link mut self
) -> Result<LinkStr<'link, Utf8Str>, Error>

WSTP C API Documentation: WSGetUTF8String()

pub fn get_utf16_str<'link>(
    &'link mut self
) -> Result<LinkStr<'link, Utf16Str>, Error>

WSTP C API Documentation: WSGetUTF16String()

pub fn get_utf32_str<'link>(
    &'link mut self
) -> Result<LinkStr<'link, Utf32Str>, Error>

WSTP C API Documentation: WSGetUTF32String()

pub fn test_head(&mut self, symbol: &str) -> Result<usize, Error>

Check that the incoming expression is a function with head symbol.

If the check succeeds, the number of elements in the incoming expression is returned. Otherwise, an error is returned.

Example

use wstp::Link;

#[derive(Debug, PartialEq)]
struct Quantity {
    value: f64,
    unit: String,
}

fn get_quantity(link: &mut Link) -> Result<Quantity, wstp::Error> {
    // Use test_head() to verify that the incoming expression has the expected
    // head.
    let argc = link.test_head("System`Quantity")?;

    assert!(argc == 2, "expected Quantity to have 2 arguments");

    let value = link.get_f64()?;
    let unit = link.get_string()?;

    Ok(Quantity { value, unit })
}

let mut link = Link::new_loopback().unwrap();
link.put_function("System`Quantity", 2).unwrap();
link.put_f64(5.0).unwrap();
link.put_str("Seconds").unwrap();

assert_eq!(
    get_quantity(&mut link),
    Ok(Quantity { value: 5.0, unit: "Seconds".into() })
);

pub fn test_head_cstr(&mut self, symbol: &CStr) -> Result<usize, Error>

Check that the incoming expression is a function with head symbol.

This method is an optimized variant of Link::test_head().

pub fn get_arg_count(&mut self) -> Result<usize, Error>

WSTP C API Documentation: WSGetArgCount()

pub fn get_i64(&mut self) -> Result<i64, Error>

WSTP C API Documentation: WSGetInteger64()

pub fn get_i32(&mut self) -> Result<i32, Error>

WSTP C API Documentation: WSGetInteger32()

pub fn get_i16(&mut self) -> Result<i16, Error>

WSTP C API Documentation: WSGetInteger16()

pub fn get_u8(&mut self) -> Result<u8, Error>

WSTP C API Documentation: WSGetInteger8()

pub fn get_f64(&mut self) -> Result<f64, Error>

WSTP C API Documentation: WSGetReal64()

pub fn get_f32(&mut self) -> Result<f32, Error>

WSTP C API Documentation: WSGetReal32()

pub fn get_i64_array(&mut self) -> Result<Array<'_, i64>, Error>

Get a multidimensional array of i64.

Example

use wstp::Link;

let mut link = Link::new_loopback().unwrap();

link.put_i64_array(&[1, 2, 3, 4], &[2, 2]).unwrap();

let out = link.get_i64_array().unwrap();

assert_eq!(out.data().len(), 4);
assert_eq!(out.dimensions(), &[2, 2]);

WSTP C API Documentation: WSGetInteger64Array()

pub fn get_i32_array(&mut self) -> Result<Array<'_, i32>, Error>

WSTP C API Documentation: WSGetInteger32Array()

pub fn get_i16_array(&mut self) -> Result<Array<'_, i16>, Error>

WSTP C API Documentation: WSGetInteger16Array()

pub fn get_u8_array(&mut self) -> Result<Array<'_, u8>, Error>

WSTP C API Documentation: WSGetInteger8Array()

pub fn get_f64_array(&mut self) -> Result<Array<'_, f64>, Error>

Get a multidimensional array of f64.

Example

use wstp::Link;

let mut link = Link::new_loopback().unwrap();

link.put_f64_array(&[3.141, 1.618, 2.718], &[3]).unwrap();

let out = link.get_f64_array().unwrap();

assert_eq!(out.data().len(), 3);
assert_eq!(out.data(), &[3.141, 1.618, 2.718]);
assert_eq!(out.dimensions(), &[3]);

WSTP C API Documentation: WSGetReal64Array()

pub fn get_f32_array(&mut self) -> Result<Array<'_, f32>, Error>

WSTP C API Documentation: WSGetReal32Array()

impl Link

pub fn put_raw_type(&mut self, type_: i32) -> Result<(), Error>

TODO: Augment this function with a put_type() method which takes a (non-exhaustive) enum value.

WSTP C API Documentation: WSPutType()

pub fn end_packet(&mut self) -> Result<(), Error>

WSTP C API Documentation: WSEndPacket()

pub fn put_str(&mut self, string: &str) -> Result<(), Error>

WSTP C API Documentation: WSPutUTF8String()

pub fn put_symbol(&mut self, symbol: &str) -> Result<(), Error>

WSTP C API Documentation: WSPutUTF8Symbol()

pub fn put_utf8_str(&mut self, utf8: &[u8]) -> Result<(), Error>

WSTP C API Documentation: WSPutUTF8String()

This function will return a WSTP error if utf8 is not a valid UTF-8 encoded string.

pub fn put_utf16_str(&mut self, utf16: &[u16]) -> Result<(), Error>

Put a UTF-16 encoded string.

This function will return a WSTP error if utf16 is not a valid UTF-16 encoded string.

WSTP C API Documentation: WSPutUTF16String()

pub fn put_utf32_str(&mut self, utf32: &[u32]) -> Result<(), Error>

Put a UTF-32 encoded string.

This function will return a WSTP error if utf32 is not a valid UTF-32 encoded string.

WSTP C API Documentation: WSPutUTF32String()

pub fn put_function<'h, H: Into<Option<&'h str>>>(
    &mut self,
    head: H,
    count: usize
) -> Result<(), Error>

Begin putting a function onto this link.

Examples

Put the expression {1, 2, 3} on the link:

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

link.put_function("System`List", 3)?;
link.put_i64(1)?;
link.put_i64(2)?;
link.put_i64(3)?;

Put the expression foo["a"]["b"] on the link:

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

link.put_function(None, 1)?;
link.put_function("Global`foo", 1)?;
link.put_str("a")?;
link.put_str("b")?;

pub fn put_arg_count(&mut self, count: usize) -> Result<(), Error>

WSTP C API Documentation: WSPutArgCount()

pub fn put_i64(&mut self, value: i64) -> Result<(), Error>

WSTP C API Documentation: WSPutInteger64()

pub fn put_i32(&mut self, value: i32) -> Result<(), Error>

WSTP C API Documentation: WSPutInteger32()

pub fn put_i16(&mut self, value: i16) -> Result<(), Error>

WSTP C API Documentation: WSPutInteger16()

pub fn put_u8(&mut self, value: u8) -> Result<(), Error>

WSTP C API Documentation: WSPutInteger8()

pub fn put_f64(&mut self, value: f64) -> Result<(), Error>

WSTP C API Documentation: WSPutReal64()

pub fn put_f32(&mut self, value: f32) -> Result<(), Error>

WSTP C API Documentation: WSPutReal32()

pub fn put_i64_array(
    &mut self,
    data: &[i64],
    dimensions: &[usize]
) -> Result<(), Error>

Put a multidimensional array of i64.

Panics

This function will panic if the product of dimensions is not equal to data.len().

WSTP C API Documentation: WSPutInteger64Array()

pub fn put_i32_array(
    &mut self,
    data: &[i32],
    dimensions: &[usize]
) -> Result<(), Error>

Put a multidimensional array of i32.

Panics

This function will panic if the product of dimensions is not equal to data.len().

WSTP C API Documentation: WSPutInteger32Array()

pub fn put_i16_array(
    &mut self,
    data: &[i16],
    dimensions: &[usize]
) -> Result<(), Error>

Put a multidimensional array of i16.

Panics

This function will panic if the product of dimensions is not equal to data.len().

WSTP C API Documentation: WSPutInteger16Array()

pub fn put_u8_array(
    &mut self,
    data: &[u8],
    dimensions: &[usize]
) -> Result<(), Error>

WSTP C API Documentation: WSPutInteger8Array()

pub fn put_f64_array(
    &mut self,
    data: &[f64],
    dimensions: &[usize]
) -> Result<(), Error>

Put a multidimensional array of f64.

Panics

This function will panic if the product of dimensions is not equal to data.len().

WSTP C API Documentation: WSPutReal64Array()

pub fn put_f32_array(
    &mut self,
    data: &[f32],
    dimensions: &[usize]
) -> Result<(), Error>

Put a multidimensional array of f32.

Panics

This function will panic if the product of dimensions is not equal to data.len().

WSTP C API Documentation: WSPutReal32Array()

impl Link

pub fn put_eval_packet(&mut self, expr: &Expr) -> Result<(), Error>

Put an EvaluatePacket[expr] onto the link.

impl Link

pub unsafe fn unchecked_ref_cast_mut(from: &mut WSLINK) -> &mut Self

Transmute a &mut WSLINK into a &mut Link.

This operation enables usage of the safe Link wrapper type without assuming ownership over the underying raw WSLINK.

Use this function to construct a Link from a borrowed WSLINK. This function should be used in LibraryLink functions loaded via LibraryFunctionLoad instead of Link::unchecked_new().

Safety

For this operation to be safe, the caller must ensure:

• the WSLINK is validly initialized.
• they have unique ownership of the WSLINK value; no aliasing is possible.

and the maintainer of this functionality must ensure:

• The Link type is a #[repr(transparent)] wrapper around around a single field of type WSLINK.

impl Link

Creating WSTP link objects

pub fn new_loopback() -> Result<Self, Error>

Create a new Loopback type link.

WSTP C API Documentation: WSLoopbackOpen()

pub fn listen(protocol: Protocol, name: &str) -> Result<Self, Error>

Create a new named WSTP link using protocol.

pub fn connect(protocol: Protocol, name: &str) -> Result<Self, Error>

Connect to an existing named WSTP link.

pub fn tcpip_listen<A: ToSocketAddrs>(addr: A) -> Result<Self, Error>

Create a new WSTP TCPIP link bound to addr.

If addr yields multiple addresses, listening will be attempted with each of the addresses until one succeeds and returns the listener. If none of the addresses succeed in creating a listener, the error returned from the last attempt (the last address) is returned.

pub fn tcpip_connect<A: ToSocketAddrs>(addr: A) -> Result<Self, Error>

Connect to an existing WSTP TCPIP link listening at addr.

If addr yields multiple addresses, a connection will be attempted with each of the addresses until a connection is successful. If none of the addresses result in a successful connection, the error returned from the last connection attempt (the last address) is returned.

pub fn connect_to_link_server<A: ToSocketAddrs>(addrs: A) -> Result<Self, Error>

Open a WSTP Protocol::TCPIP connection to a LinkServer.

If addrs yields multiple addresses, a connection will be attempted with each of the addresses until a connection is successful. If none of the addresses result in a successful connection, the error returned from the last connection attempt (the last address) is returned.

pub fn connect_with_options(
    protocol: Protocol,
    name: &str,
    options: &[&str]
) -> Result<Self, Error>

pub fn open_with_args(args: &[&str]) -> Result<Self, Error>

WSTP C API Documentation: WSOpenArgcArgv()

This function can be used to create a Link of any protocol and mode. Prefer to use one of the constructor methods listed below when you know the type of link to be created.

• Link::listen()
• Link::connect()
• Link::tcpip_listen()
• Link::tcpip_connect()
• Link::connect_to_link_server()

pub unsafe fn unchecked_new(raw_link: WSLINK) -> Self

Construct a Link from a raw WSLINK pointer.

pub fn activate(&mut self) -> Result<(), Error>

WSTP C API Documentation: WSActivate()

pub fn close(self)

Close this end of the link.

WSTP C API Documentation: WSClose()

impl Link

Link properties

pub fn link_name(&self) -> String

Get the name of this link.

WSTP C API Documentation: WSLinkName()

pub fn is_ready(&self) -> bool

Check if there is data ready to be read from this link.

WSTP C API Documentation: WSReady()

pub fn is_loopback(&self) -> bool

WSTP C API Documentation: WSIsLinkLoopback()

pub fn error(&self) -> Option<Error>

Returns an Error describing the last error to occur on this link.

Examples

TODO: Example of getting an error code.

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

Returns a string describing the last error to occur on this link.

TODO: If the most recent operation was successful, does the error message get cleared?

WSTP C API Documentation: WSErrorMessage()

pub fn clear_error(&mut self)

Clear errors on this link.

WSTP C API Documentation: WSClearError()

pub unsafe fn raw_link(&self) -> WSLINK

WSTP C API Documentation: WSLINK

pub unsafe fn user_data(&self) -> (*mut c_void, WSUserFunction)

WSTP C API Documentation: WSUserData

pub unsafe fn set_user_data(
    &mut self,
    data_obj: *mut c_void,
    user_func: WSUserFunction
)

WSTP C API Documentation: WSSetUserData

impl Link

Reading and writing expressions

pub fn flush(&mut self) -> Result<(), Error>

Flush out any buffers containing data waiting to be sent on this link.

WSTP C API Documentation: WSFlush()

pub fn raw_get_next(&mut self) -> Result<i32, Error>

WSTP C API Documentation: WSGetNext()

pub fn raw_next_packet(&mut self) -> Result<i32, Error>

WSTP C API Documentation: WSNextPacket()

pub fn new_packet(&mut self) -> Result<(), Error>

WSTP C API Documentation: WSNewPacket()

pub fn get_expr(&mut self) -> Result<Expr, Error>

Read an expression off of this link.

pub fn put_expr(&mut self, expr: &Expr) -> Result<(), Error>

Write an expression to this link.

pub fn transfer_expr_to(&mut self, dest: &mut Link) -> Result<(), Error>

Transfer an expression from this link to another.

Example

Transfer an expression between two loopback links:

use wstp::Link;

let mut a = Link::new_loopback().unwrap();
let mut b = Link::new_loopback().unwrap();

// Put an expression into `a`
a.put_i64(5).unwrap();

// Transfer it to `b`
a.transfer_expr_to(&mut b).unwrap();

assert_eq!(b.get_i64().unwrap(), 5);

WSTP C API Documentation: WSTransferExpression()

pub fn transfer_to_end_of_loopback_link(
    &mut self,
    dest: &mut Link
) -> Result<(), Error>

Transfer the full contents of this loopback link to dest.

WSTP C API Documentation: WSTransferToEndOfLoopbackLink()

Panics

This function will panic if !self.is_loopback().

Trait Implementations

impl Debug for Link

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Link

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Link

Safety

Links can be sent between threads, but they cannot be used from multiple threads at once (unless WSEnableLinkLock() has been called on the link). So Link satisfies Send but not Sync.

TODO: Add a wrapper type for Link which enforces that WSEnableLinkLock() has been called, and implements Sync.