10 releases (4 breaking)
Uses new Rust 2021
new 0.5.0  Aug 11, 2022 

0.4.2  Aug 10, 2022 
0.3.3  Aug 5, 2022 
0.2.0  Aug 3, 2022 
0.1.2  Jul 27, 2022 
#76 in Science
308 downloads per month
155KB
4K
SLoC
Rustmex
A library providing convenient Rust bindings to Matlab's MEX C api.
Rustmex makes writing MEX functions in Rust a bit easier. It convert Matlab types, and
the arguments it provides to mexFunction
into more Rusty types, which can then be used
to interface with other Rust code easily.
In this readme:
Installation
The installation of this crate is slightly more involved than you might be used to: you
need to select a target API. This target API depends on what version of Matlab or
GNU/Octave you are targeting with your library. See the API section for that.
Once you've selected your target API, put the following in your Cargo.toml
:
rustmex = { version = "0.5.0", features = ["matlab_interleaved"] }
where "matlab_interleaved"
is then one of the options for target APIs.
Furthermore, if want to use rustmex to write a MEX file, you need to add the following to
your Cargo.toml
file too:
[lib]
cratetype = ["cdylib"]
Compiling your crate then results in a C dynamic library, instead of a Rust library.
Compilation and linkage
On some platforms with some target API's (in particular Windows with Matlab; your milage may vary with Octave), you might need to tell the linker where some libraries are located.
On those platforms, Rustmex's build script unconditionally fails if you don't tell the linker where the libraries are located. Otherwise you will run into one impenetrable error, while with the build script failing you get a nice error message.
You tell the linker where the libraries are located by overriding the build script
In a config.toml
like the
following:
[target.<triple>.mex]
rustclinksearch = ["~/bin/R2022a/bin/glnxa64"]
rustclinklib = ["mx", "mex", "mat"]
you set the appropriate triplet, library search path, and libraries to link. Substitute
<triple>
with the triple you are compiling for (the "host" field of the output of
rustc vV
). Matlab will print the appropriate search path when you run
fullfile(matlabroot(), 'bin', computer('arch'))
in your Matlab prompt.
If you are on another platform than Matlab on Windows, and the compilation still fails
with a linker error, you might also need to do this process there. Create an empty C file
test.c
for example, and "dry run" the creation of a mex file from it. For matlab, you
can do this with mex n test.c
, for Octave with mkoctfile n test.c mex
. Look, on
the second line, for arguments starting with L
and l
, and substitute these in the
config.toml
file for the link search path and link library path respectively.
Usage
Each MEX function file has an entrypoint called mexFunction
. This is a C FFI function,
which, preferably, you do not want to write yourself.
Instead, rustmex provides the entrypoint macro; a macro to mark your Rust entrypoint with. For example:
use rustmex::prelude::*;
#[rustmex::entrypoint]
fn hello_world(lhs: Lhs, rhs: Rhs) > rustmex::Result<()> {
println!("Hello Matlab!");
Ok(())
}
Note that this example mirrors the definition of mexFunction
itself: Matlab has already
allocated a return value array, you just need to place your results into it.
The FromMatlabError
is for when you want to convert an mxArray into a more Rusty data
type. These conversions are not infallible: Matlab is dynamically typed, and the provided
mxArray
must have the same type and size as the type we want to convert it into.
As a more convoluted example:
use rustmex::prelude::*;
#[rustmex::entrypoint]
fn euclidean_length(lhs: Lhs, rhs: Rhs) > rustmex::Result<()> {
let v: &[f64] = rhs
.get(0)
.error_if_missing("euclidean_length:missing_input",
"Missing input vector to compute the length of")?
.data_slice()?;
// I recommend to only execute your planned computation once you're sure it
// actually needs to be computed — it's a bit of a waste to compute an expensive
// result without somewhere to return it to.
if let Some(ret) = lhs.get_mut(0) {
ret.replace(v.iter().map(xx*x).sqrt().to_matlab());
}
Ok(())
}
This example computes the Euclidean length of an input vector. Note that type annotations
are (almost always) needed for the return type of data_slice()
and from_matlab()
.
Regarding [FromMatlab
][convert::FromMatlab
], this library also supports building
NDarrays from mxArrays. It will ensure that NDarray understands the data the same way
matlab does. For example, the following prints out a debug representation of the array:
use rustmex::prelude::*;
use ndarray::ArrayViewD;
#[rustmex::entrypoint]
fn display_matrix(lhs: Lhs, rhs: Rhs) > rustmex::Result<()> {
if let Some(mx) = rhs.get(0) {
let mat = ArrayViewD<f64>::from_matlab(mx)?;
eprintln!("{mat:#?}");
}
Ok(())
}
Calling back into Matlab is also supported. For example, to compute the square root of the sum of squares (i.e. ndpythagoras):
% Call Rust MEX file
x = rusty_fn_call(@(x) sqrt(sum(x.^2)), 1:10)
use rustmex::prelude::*
use rustmex::function::Function;
#[rustmex::entrypoint]
fn rusty_fn_call(lhslice: rustmex::Lhs, rhslice: rustmex::Rhs) > rustmex::Result<()> {
let f = rhslice
.get(0)
.error_if_missing("rusthello:no_fn", "Didn't get a function")?
.to_rust::<Function<_>>()?;
if let Some(r) = lhslice.get_mut(0) {
// Just forward the remaining arguments
let mut results: Box<[Option<MxArray>; 1]> = f.call(&rhslice[1..]).unwrap();
let v = results[0].take().unwrap();
r.replace(v);
};
return Ok(());
}
prints:
x = 19.621
If you assume something about the data you receive, but it might not yet be in the right
shape, you might want to reshape. Rustmex enables ergonomically reshaping data: you can
apply the ?
operator on a Result
with a ShapeError
in functions which return a
rustmex::Result
:
use rustmex::prelude::*;
use ndarray::{ArrayViewD, Ix2};
#[rustmex::entrypoint]
fn display_matrix(lhs: Lhs, rhs: Rhs) > rustmex::Result<()> {
if let Some(mx) = rhs.get(0) {
let mat = ArrayViewD<f64>::from_matlab(mx)?
.into_dimensionality<Ix2>()?
.into_shape((1, 4))?;
eprintln!("{mat:#?}");
}
Ok(())
}
Design and Internals
Writing MEX extensions is not as straightforward as you might be useful. In particular, Matlab (by default) breaks some fundamental assumptions Rust makes on memory management. do not skip over the memory management section.
Ergonomics
The design of the library consists of three levels:
 The Raw FFI level: the C FFI definitions
 The wrapped mex level: functionality wrapping the raw level for a more ergonomic and safe Rust interface
 Top level: Wrapping the mex level, providing easy conversions to and from mxArrays.
It is recommended to write against the level which supports your features. If Rustmex does not implement functionality you need, the lower levels are still available for that.
APIs
Rustmex wraps the bindings exposed by Matlab (pre and post 2017b) and GNU/Octave. The features these bindings provide are all slightly different, so select one via a cargo feature. These are:
matlab_interleaved
: Matlab, release 2018a and later, with the interleaved complex API;matlab_separated
: Matlab, release 2017b and earlier, with the separate real and complex parts of mxArrays;octave
: for GNU/Octave. (uses the same representation as matlab_separated)
If you've compiled your crate as a cdylib
, you can then take the resultant dynamic
library (on linux a .so
), copy it to the target location in your Matlab path, with the
appropriate file extension. (.mexa64
for MEX on 64 bit Linux, .mexw64
for MEX on
Windows, and .mex
for GNU/Octave.)
Some of these targets also use symbol versioning, so e.g. mxCreateNumericArray
is
actually mxCreateNumericArray_800
for the matlab_interleaved API. For ease of use,
rustmex renames (pub use $x_$v as $x
) these symbols to all have the same name in
[mex::raw].
When Rustmex is compiled for an API which represents complex values with two arrays, slightly different implementations for data conversions are used. Since most Rust code assumes that complex values are interleaved (i.e., the real and imaginary parts of the value are stored next to eachother in memory) this might cause a lot of copying on the interface.
See also https://nl.mathworks.com/help/matlab/matlab_external/matlabsupportforinterleavedcomplex.html.
Memory Management
The Mex API has a few quirks when it comes to memory management. In particular,
allocations made via mxMalloc
are, by default, deallocated when the MEX function
returns. This causes problems when some part of Rust code assumes that they are
responsible for deallocating the memory and assuming it is still after. Rustmex therefore
marks all allocations as persistent via mexMakeMemoryPersistent
. This may cause your
MEX function to leak instead of crash (the latter takes Matlab with it). See also
[mex::alloc::mxAlloc
].
TODO
 Structs and Objects
 From/To
Array<HashMap<Field, Value>>
 From/To Rust struct via procmacro?
 From/To
 Other conversion targets
 Support matlab character arrays, strings
 Nalgebra?
 Better error handling
 Ergonomically return some error trait object.
 Compose well with other error handling libraries; break down elegantly via std::Error
 Wrapping MEX functionality

mexAtExit
(also important for dropping static values. 
mexLock
/mexUnlock

mexGetVariablePtr
/mexGetVariable
/mexPutVariable
 Calling back into Matlab

Licence
This is licensed to you under the Mozilla Public License, version 2. You can the licence in the LICENCE file in this project's source tree root folder.
Authors
 Niels ter Meer (maintainer)
Dependencies
~1.5MB
~26K SLoC