mono-api-internal.html

# Mono Internals

This section documents some of the internal APIs used inside Mono that developers extending or altering Mono might want to use.

## Strings

### Other Encodings

These routines are used when coping with strings that come from Mono's environment, and might be encoded in one or more of the external encodings.

For example, some file systems might historically contain a mix of file names with both old and new encodings, typically UTF8 for new files, and the old files would be encoded in an 8 bit character set (ISO-8859-1 for example).

These routines try a number of encodings, those specified in the `MONO_ENCODINGS` environment variable and return unicode strings that can be used internally.

See the mono(1) man page for more details.
`mono_unicode_from_external`
Syntax
gunichar2*mono_unicode_from_external (const gchar *in, gsize *bytes)

Parameters

in | pointers to the buffer.
bytes | number of bytes in the string.

Description
Tries to turn a `NULL`-terminated string into UTF-16.

First, see if it's valid UTF-8, in which case just turn it directly into UTF-16. Next, run through the colon-separated encodings in `MONO_EXTERNAL_ENCODINGS` and do an `iconv` conversion on each, returning the first successful conversion to UTF-16. If no conversion succeeds, return `NULL`.

Callers must free the returned string if not `NULL`. bytes holds the number of bytes in the returned string, not including the terminator.
`mono_unicode_to_external`
Syntax
gchar*mono_unicode_to_external (const gunichar2 *uni)

Parameters

uni | a UTF-16 string to convert to an external representation.

Description
Turns `NULL`-terminated UTF-16 into either UTF-8, or the first working item in `MONO_EXTERNAL_ENCODINGS` if set. If no conversions work, then UTF-8 is returned. Callers must free the returned string.
`mono_utf8_from_external`
Syntax
gchar*mono_utf8_from_external (const gchar *in)

Parameters

in | pointer to the string buffer.

Description
Tries to turn a `NULL`-terminated string into UTF8.

First, see if it's valid UTF-8, in which case there's nothing more to be done. Next, run through the colon-separated encodings in `MONO_EXTERNAL_ENCODINGS` and do an `iconv` conversion on each, returning the first successful conversion to UTF-8. If no conversion succeeds, return `NULL`.

Callers must free the returned string if not `NULL`.

This function is identical to `mono_unicode_from_external`, apart from returning UTF-8 not UTF-16; it's handy in a few places to work in UTF-8.

## Marshalling functions

`mono_marshal_alloc`
Syntax
void* mono_marshal_alloc (gsize size, MonoError *error)

`mono_marshal_asany`
Syntax
gpointer mono_marshal_asany_impl (MonoObjectHandle o, MonoMarshalNative string_encoding, int param_attrs, MonoError *error)

Description
This is a JIT icall, it sets the pending exception (in wrapper) and returns `NULL` on error.
`mono_marshal_free_array`
Syntax
void mono_marshal_free_array (gpointer *ptr, int size)

`mono_marshal_free_asany`
Syntax
void mono_marshal_free_asany_impl (MonoObjectHandle o, gpointer ptr, MonoMarshalNative string_encoding, int param_attrs, MonoError *error)

Description
This is a JIT icall, it sets the pending exception (in wrapper)
`mono_marshal_free`
Syntax
void mono_marshal_free (gpointer ptr)

`mono_marshal_get_castclass`
Syntax
mono_marshal_get_castclass

`mono_marshal_get_delegate_begin_invoke`
Syntax
MonoMethod* mono_marshal_get_delegate_begin_invoke (MonoMethod *method)

`mono_marshal_get_delegate_end_invoke`
Syntax
MonoMethod* mono_marshal_get_delegate_end_invoke (MonoMethod *method)

`mono_marshal_get_delegate_invoke`
Syntax
MonoMethod* mono_marshal_get_delegate_invoke (MonoMethod *method, MonoDelegate *del)

Description
The returned method invokes all methods in a multicast delegate.
`mono_marshal_get_icall_wrapper`
Syntax
MonoMethod* mono_marshal_get_icall_wrapper (MonoJitICallInfo *callinfo, gboolean check_exceptions)

Description
Generates IL code for the JIT icall wrapper. The generated method calls the unmanaged code in callinfo->func.
`mono_marshal_get_isinst`
Syntax
mono_marshal_get_isinst

`mono_marshal_get_ldfld_wrapper`
Syntax
MonoMethod* mono_marshal_get_ldfld_wrapper (MonoType *type)

Parameters

type | the type of the field

Description

This method generates a function which can be use to load a field with type type from an object. The generated function has the following signature:

`type ldfld_wrapper (MonoObject *this_obj, MonoClass *klass, MonoClassField *field, int offset)`
`mono_marshal_get_managed_wrapper`
Syntax
MonoMethod* mono_marshal_get_managed_wrapper (MonoMethod *method, MonoClass *delegate_klass, uint32_t target_handle, MonoError *error)

Description
Generates IL code to call managed methods from unmanaged code If target_handle is `0`, the wrapper info will be a `WrapperInfo` structure.
`mono_marshal_get_native_wrapper`
Syntax
MonoMethod* mono_marshal_get_native_wrapper (MonoMethod *method, gboolean check_exceptions, gboolean aot)

Parameters

method | The `MonoMethod` to wrap.
check_exceptions | Whenever to check for pending exceptions

Description

Generates IL code for the pinvoke wrapper. The generated method calls the unmanaged code in `piinfo->addr`.
`mono_marshal_get_proxy_cancast`
Syntax
MonoMethod* mono_marshal_get_proxy_cancast (MonoClass *klass)

`mono_marshal_get_ptr_to_struct`
Syntax
MonoMethod* mono_marshal_get_ptr_to_struct (MonoClass *klass)

Parameters

klass | `MonoClass`

Description
Generates IL code for `PtrToStructure (IntPtr src, object structure)`
`mono_marshal_get_remoting_invoke_for_target`
Syntax
MonoMethod* mono_marshal_get_remoting_invoke_for_target (MonoMethod *method, MonoRemotingTarget target_type, MonoError *error)

`mono_marshal_get_remoting_invoke`
Syntax
MonoMethod* mono_marshal_get_remoting_invoke (MonoMethod *method, MonoError *error)

`mono_marshal_get_remoting_invoke_with_check`
Syntax
MonoMethod* mono_marshal_get_remoting_invoke_with_check (MonoMethod *method, MonoError *error)

`mono_marshal_get_runtime_invoke`
Syntax
MonoMethod* mono_marshal_get_runtime_invoke_full (MonoMethod *method, gboolean virtual_, gboolean need_direct_wrapper)

Parameters

function |

Description

`MonoObject *runtime_invoke (MonoObject *this_obj, void **params, MonoObject **exc, void* method)`

We also catch exceptions if exc is not `NULL`. If virtual is `TRUE`, then method is invoked virtually on this. This is useful since it means that the compiled code for method does not have to be looked up before calling the runtime invoke wrapper. In this case, the wrapper ignores its method argument.
`mono_marshal_get_stelemref`
Syntax
MonoMethod* mono_marshal_get_stelemref (void)

`mono_marshal_get_stfld_wrapper`
Syntax
MonoMethod* mono_marshal_get_stfld_wrapper (MonoType *type)

Parameters

type | the type of the field

Description

This method generates a function which can be use to store a field with type type. The generated function has the following signature:

`void stfld_wrapper (MonoObject *this_obj, MonoClass *klass, MonoClassField *field, int offset, type val)`
`mono_marshal_get_struct_to_ptr`
Syntax
MonoMethod* mono_marshal_get_struct_to_ptr (MonoClass *klass)

Parameters

klass | `MonoClass`

Description

Generates IL code for `StructureToPtr (object structure, IntPtr ptr, bool fDeleteOld)`
`mono_marshal_get_synchronized_wrapper`
Syntax
MonoMethod* mono_marshal_get_synchronized_wrapper (MonoMethod *method)

Parameters

wrapper | the generated method

Description
calls method while locking `this` or the parent type.
`mono_marshal_get_unbox_wrapper`
Syntax
MonoMethod* mono_marshal_get_unbox_wrapper (MonoMethod *method)

Description
The returned method calls method unboxing the `this` argument.
`mono_marshal_get_xappdomain_invoke`
Syntax
MonoMethod* mono_marshal_get_xappdomain_invoke (MonoMethod *method, MonoError *error)

Description
Generates a fast remoting wrapper for cross app domain calls.
`mono_marshal_load_type_info`
Syntax
MonoMarshalType* mono_marshal_load_type_info (MonoClass* klass)

Description

Initialize `klass::marshal_info` using information from metadata. This function can recursively call itself, and the caller is responsible to avoid that by calling `mono_marshal_is_loading_type_info` beforehand.

LOCKING: Acquires the loader lock.
`mono_marshal_method_from_wrapper`
Syntax
MonoMethod* mono_marshal_method_from_wrapper (MonoMethod *wrapper)

`mono_marshal_set_last_error`
Syntax
void mono_marshal_set_last_error (void)

Description

This function is invoked to set the last error value from a P/Invoke call which has `SetLastError` set.
`mono_marshal_type_size`
Syntax
gint32 mono_marshal_type_size (MonoType *type, MonoMarshalSpec *mspec, guint32 *align, gboolean as_field, gboolean unicode)

## Metadata Loader Locking: Internals

The locking functions here are used by code in class.c and metadata.c to lock access to the shared hashtables inside the MonoImage.
`mono_loader_lock`
Syntax
void mono_loader_lock (void)

Description

See `docs/thread-safety.txt` for the locking strategy.
`mono_loader_unlock`
Syntax
void mono_loader_unlock (void)

## Garbage Collector Internal Interface

The internal interface of the Mono GC is the interface used between the runtime engine and the garbage collector.
`mono_gc_alloc_fixed`
Syntax
MonoObject* mono_gc_alloc_fixed (size_t size, MonoGCDescriptor descr, MonoGCRootSource source, void *key, const char *msg)

`mono_gc_free_fixed`
Syntax
void mono_gc_free_fixed (void* addr)

`mono_gc_make_descr_from_bitmap`
Syntax
SgenDescriptor mono_gc_make_descr_from_bitmap (gsize *bitmap, int numbits)

`mono_gc_base_init`
Syntax
void mono_gc_base_init (void)

`mono_gc_invoke_finalizers`
Syntax
int mono_gc_invoke_finalizers (void)

`mono_gc_is_gc_thread`
Syntax
gboolean mono_gc_is_gc_thread (void)

`mono_gc_pending_finalizers`
Syntax
MonoBoolean mono_gc_pending_finalizers (void)

`mono_gc_register_thread`
Syntax
mono_gc_register_thread