Macro dymod::dymod [−] [src]

macro_rules! dymod {
    (
        #[path = $libpath: tt]
        pub mod $modname: ident
        {
            $(fn $fnname: ident ( $($argname: ident : $argtype: ty),* ) -> $returntype: ty;)*
        }
    ) => { ... };
}

Takes a module definition and allows it to be hotswapped in debug mode.

Examples

dymod!
{
    #[path = "../subcrate/src/lib.rs"]
    pub mod subcrate
    {
        fn count_sheep(sheep: u32) -> &'static str;
    }
}

This creates a module with a single function, count_sheep. In debug mode, this function will call into the dynamically loaded subcrate dylib. If that crate is recompiled, this function will use the updated code.

In release mode, this module becomes just a regular Rust module with the contents of ../subcrate/src/lib.rs. No dynamic linking is performed at all, and the functions are as safe as if they were included normally in this crate.

Panics

Panics can occur only in debug mode as a result of the various pitfalls of dynamic linking. These can be the result of:

  1. Dropping data which was allocated in the other library.
  2. Holding onto references to data that is dropped when the dylib is hotswapped.
  3. Changing the definition of a struct that is passed to or from the other library.
  4. Very many other things.

These problems should all disappear in release mode, where this code is just statically linked as normal.

Safety

As above, dynamic linking is inherently unsafe. In debug mode, these things can cause a variety of undefined behaviour. For example, see sharedlib, which this crate uses internally.