Crate wrapped_mono

wrapped_mono is a safe, lightweight wrapper around the mono library. It allows embedding of the mono runtime inside a rust project. Inside this embedded runtime code written in languages supporting the .NET framework, such as C# and F#, can be run. This allows usage of libraries written in those languages, and using them as a scripting language. The mono runtime is used by many game engines, and this wrapper allows using it with projects written in Rust too.

Safety

Most functions are safe and when invalid data is passed will fail in a controlled way with an error message. There are still some pitfalls, because not all errors can be caught without substantial overhead. Those errors are hard to come by, and should be always clearly marked in the documentation(for example accessing an object after deleting it by deleting domain it is in), and easy to spot.

Definitions of certain words used in documentation:

Managed Code - code which runs in the runtime(e.g. C# code)

Unmanaged code - code which runs outside runtime(in this case Rust code)

More precise explanation

Feature flags

• unsafe_boxing — Disables boxing/unboxing safety checks. Normally, when an object is unboxed, it’s type is checked to prevent crashes and errors. Enabling unsafe_unboxing will make wrapped_mono assume that type given by the user is always correct.

• unsafe_arrays — Disables array safety checks. Normally, when an array is created, it will make checks to ensure that its managed type matches its unmanaged type.

• unsafe_speedup — Disables all safety checks to slightly speed wrapped_mono up. Gains are usually negligible and potential errors will have more cryptic messages(Segfaluts instead of failed assertions). USE WITH CAUTION.

• build_test_dlls — Build test dlls. Enable only for tests, if you want to change test .cs files.

• regen_binds — Regenerates bindings for mono library

• dump_macro_results — Dumps code created as results of macros into “macro.dump” file. Use for debugging when macros do not behave as expected.

• referneced_objects (enabled by default) — Prevents objects in use by rust from being removed by mono runtime, adds slight overhead but is essential for storing objects long term. Can be disabled, but disabling it forces manual management of object lifetimes using GC handles.

• old_gc_unsafe — Uses some old variants of mono API. Try if mono_threads_enter_gc_unsafe_region symbol is missing during linking.

Example

use wrapped_mono::*;
fn main(){
    // Initialise the runtime with default version(`None`), and root domian named "main_domain"
    let domain = jit::init("main_domain",None);

    // Load assembly "SomeAssembly.dll"
    let assembly = domain.assembly_open("SomeAssembly.dll").expect("Could not load assembly!");
    // Get the image, the part of assembly containing executable code(classes,methods, etc.)
    let image = assembly.get_image();
    // Get class named SomeClass in SomeNamespace
    let class = Class::from_name(&image,"SomeNamespace","SomeClass").expect("Could not find SomeClass!");
    // Create an instance of this class
    let instance = Object::new(&domain,&class);
    // Creating an instance of a class DOES NOT CALL ITS CONSTRUCTOR. The constructor is a method named '.ctor', that has to be called separately

    // Get a constructor method of SomeClass accepting an integer and a string (2 parameters)
    let ctor:Method<(i32,String)> = Method::get_from_name(&class,".ctor(int,System.String)",2).expect("Could not find the constructor!");
    // Call the constructor
    ctor.invoke(Some(instance.clone()),(12,"SomeString".to_owned())).expect("Got an exception while calling the constructor!");
    // Get a method "DoABackflip" form SomeClass with 1 parameter of type int returning a byte
    let met:Method<(i32,String)> = Method::get_from_name(&class,"DoABackflip",1).expect("Could not find method \"DoABackFlip\"!");
    // Call "DoABackflip" method on an instance
    let res_obj = met.invoke(Some(instance),(32,"Message".to_owned())).expect("Got an exception while calling DoABackflip!").expect("Got null from DoABackFlip");
    // Unbox the result to get a raw integer from a boxed integer
    let res = res_obj.unbox::<u8>();
    // Create a function with the special "invokable" attribute
    #[invokable]
    fn sqrt(input:f32)->f32{
        if input < 0.0{
            // can't get sqrt of a negative number, so create a managed exception and throw it.
            unsafe{Exception::arithmetic().raise()};
        }
        input.sqrt()
    }
    // Replace a method with "[MethodImplAttribute(MethodImplOptions.InternalCall)]" atribute with a rust function
    add_internal_call!("SomeClass::SqrtInternalCall",sqrt);
    // This supports all types with `InteropRecive` trait
    #[invokable]
    fn avg(input:Array<Dim1D,f32>)->f32{
        let mut avg = 0.0;
        for i in 0..input.len(){
            let curr = input.get([i]);// get the element at index i
            avg += curr/(input.len() as f32);
          }
        avg
    }
    // Replace a method with "[MethodImplAttribute(MethodImplOptions.InternalCall)]" attribute with a rust function
    add_internal_call!("SomeClass::AvgInternalCall",sqrt);
}

Re-exports

• pub use dimensions::*;

Modules

• array
  Utilities related to managed arrays.
• assembly
  Functions and types related to MonoAssembly type.
• class
  Representation of managed classes and utilities related to them.
• dimensions
• domain
  Safe representation of a delegate. Functions and types related to MonoDomain type.
• exception
  Utilities related to Exceptions.
• gc
  Functions related to garbage collection.
• image
  Part of assembly holding the executable code.
• interop
  Traits related to passing data between managed and unmanaged classes.
• jit
  Functions related to Mono JIT Runtime
• metadata
  Utilities related to metadata. Bare bones and experimental.
• method
  Safe representation of Methods(functions) form managed code an utilities related to managing and calling them.
• mstring
  Managed string utilities.
• object
  Utilities related to managed objects.
• reflection_type
  Safe representation of the System.Type type.
• runtime
  Functions related to getting data about and configuring mono runtime.
• wrapped_mono_macros
  Custom macros used by wrapped_mono

Macros

• add_internal_call
  Macro equivalent of mono_add_internal_call with automatic support for type conversion. Allows you to expose a function as an internal call

Structs

• Array
  Safe, rust representation of MonoArray (a reference to a managed array).
• Assembly
  Safe representation of an executable file containing managed code and data about it.
• Class
  Safe representation of a managed class.(eg. System.Int64, System.Object, etc.);
• ClassField
  Representation of a class field. Accessors(getters,setters and indexers) are not fields, but properties! For them use ClassProperity
• ClassProperity
  Representation of class property(getters,setters) not a class field!
• Domain
  Safe representation of [MonoDomain] type.
• Exception
  Safe representation of MonoException.
• Image
  Safe representation of [MonoImage], the part of [MonoAssembly] holding CLI code.
• MString
  Representaiton of Object of type System.String.
• Method
  Rust representation of a managed method(function of code loaded into mono runtime). Args - Tuple type of types of all arguments accepted by this particular method.
• Object
  Safe representation of a refernece to a manged Object. Is not nullable when passed between managed and unmanged code(e.g when added as an argument to function exposed as an interna call). It means that while it may represent a nullable type, wrapped-mono will automaticly panic when recived null value. For nullable support use Option<Object>.
• ReflectionType
  Rust representation of managed object derived form class System.Type

Traits

• InteropBox
  Trait allowing for boxing and unboxing type from objects
• InteropClass
  Trait allowing managed class representing this type to be got. Type of value Self::InteropSend::TargetType must match managed type represented by Class returned by get_mono_class.
• InteropRecive
  Trait specifying how to convert a type when transferring it between managed and unmanaged code. It specifies how to convert SourceType used by MonoRuntime to type implementing this trait.
• InteropSend
  Trait specifying how to convert a type when transferring it between managed and unmanaged code. It specifies how to convert type implementing this trait to TargetType used by MonoRuntime.
• ObjectTrait
  Trait contining functions common for all types of manged objects.

Attribute Macros

• invokable
  Macro creating a wrapper around a function making it able to be exposed as internal call.

Derive Macros

• InteropRecive
  Autoimplement InteropRecive trait for any type containing only IteropRecive implementing memebers. Currently supports only structs, and trivial enums(C-like enums) of size less than u64(C# max enum size).
• InteropSend
  Autoimplement InteropSend trait for any type containing only IteropSend implementing members. Currently supports only structs, and trivial enums(C-like enums) of size less than u64(C# max enum size).