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.

Modules

array

Utilities related to managed arrays.

assembly

Functions and types related to MonoAssembly type.

binds

Autognerated, unsafe binds to mono library

class

Representation of managed classes and utilities related to them.

delegate

Safe representation of a delegate.

domain

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.

profiler

Experimental Profiler API. Bare bones and may contain bugs.

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 representation of MonoArray(a reference to a managed array). Requires it’s generic argument to implement InvokePass in order to automatically convert value from managed type to rust type. Will panic on creating an array with type mismatch between runtime and rust.

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!

Delegate

A safe representation of a delegate. Args - a Tuple type made from types of all arguments accepted by this particular delegate

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

DelegateTrait

Trait implemented only for Delegate type. Splits some functions up from from main Method type, allowing for different amount of delegate arguments.

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

Tratit specifing how to convert a type when transfering it between managed and unmanaged code. It specifies how to convert SourceType used by MonoRuntime to type implementing this trait.

InteropSend

Tratit specifing how to convert a type when transfering it between managed and unmanaged code. It specifies how to convert type implementing this trait to TargetType used by MonoRuntime.

MethodTrait

Trait implemented only for Method type. Spiliting it from main Method type allows for different amount of method arguments.

ObjectTrait

Trait contining functions common for all types of manged objects.

Functions

except_managed

Variant of except which instead of panicking will raise a managed exception.

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).