dymod
This crate provides a macro, dymod!
, which allows you to specify a Rust module which will by dynamically loaded and hotswapped in debug mode, but statically linked in release mode.
Note that this is very much experimental. The current version of this crate is very opinionated about how you structure your dynamic code. Hopefully this will be relaxed a little in future.
Usage
Your dynamically loaded code should be placed in its own sub-crate under your main crate:
mycrate/
Cargo.toml
src/
main.rs
subcrate/
Cargo.toml
src/
lib.rs
Your subcrate must also be compiled as a dylib, so in your subcrate/Cargo.toml
add:
[]
= ["dylib"]
Now you need to add the code that you want to hotswap. Any functions should be pub
and #[no_mangle]
. See the Limitations section below for what kind of code you can put here.
// subcrate/src/lib.rs
Finally, use the dymod!
macro to specify your module, along with the functions that are dynamically available from it.
// mycrate/src/main.rs
extern crate dymod;
dymod!
Safety
This is really, really unsafe! But only in debug mode. In release mode, the module you specify is linked statically as if it was a regular module, and there should be no safety concerns.
Here is a partial list of what can go wrong in debug mode:
- If you are holding on to data owned by the dylib when the dylib is hotswapped, you will get undefined behaviour.
- If you take ownership of any data allocated by the dylib, dropping that data will probably cause a segfault.
- If you change the definition of a struct on either side of the boundary, you could get undefined behaviour
Limitations
So as described above, you cannot rely on hotswapping to work if you change struct definitions while your code is running.
You also cannot reliably take ownership of heap allocated data from one side of the boundary to the other.
Generic functions will not work either.
This is again, just a partial list. There really are quite a lot of constraints on what you can do.
So what is this actually good for then?
I suppose we'll see!
Here are some examples of code that should work and would be useful to hotswap: