Application Domains

Synopsis

#include <metadata/appdomain.h> /* Managed AppDomain */ typedef struct _MonoAppDomain MonoAppDomain; /* Unmanaged representation */ typedef struct _MonoDomain MonoDomain; /* Represents System.Runtime.Remoting.Contexts.Context */ typedef struct _MonoAppContext MonoAppContext

Application domains are used to isolate multiple applications on a single Mono virtual machine. They are conceptually similiar to processes, the difference is that processes are managed by the operating system, while application domains are managed by the Mono virtual machine.

For more information on applications domains see the AppDomain FAQ.

The MonoDomain is the unmanaged representation of the System.AppDomain managed type, while the MonoAppDomain type represents the managed version (MonoAppDomain has a pointer to a MonoDomain).

mono_domain_assembly_open
Syntax
MonoAssembly* mono_domain_assembly_open (MonoDomain *domain, const char *name)

Parameters
domain the application domain
name file name of the assembly
mono_domain_create
Syntax
MonoDomain* mono_domain_create (void)

Return value
New initialized MonoDomain, with no configuration or assemblies loaded into it.
Description

Creates a new application domain, the unmanaged representation of the actual domain.

Application domains provide an isolation facilty for assemblies. You can load assemblies and execute code in them that will not be visible to other application domains. This is a runtime-based virtualization technology.

It is possible to unload domains, which unloads the assemblies and data that was allocated in that domain.

When a domain is created a mempool is allocated for domain-specific structures, along a dedicated code manager to hold code that is associated with the domain.

mono_domain_create_appdomain
Syntax
MonoDomain* mono_domain_create_appdomain (char *friendly_name, char *configuration_file)

Parameters
friendly_name The friendly name of the appdomain to create
configuration_file The configuration file to initialize the appdomain with
Return value
a MonoDomain initialized with the appdomain
mono_domain_finalize
Syntax
gboolean mono_domain_finalize (MonoDomain *domain, guint32 timeout)

Parameters
domain the domain to finalize
timeout msecs to wait for the finalization to complete, -1 to wait indefinitely
Return value
TRUE if succeeded, FALSE if there was a timeout
Description

Request finalization of all finalizable objects inside domain. Wait timeout msecs for the finalization to complete.

mono_domain_foreach
Syntax
void mono_domain_foreach (MonoDomainFunc func, gpointer user_data)

Parameters
func function to invoke with the domain data
user_data user-defined pointer that is passed to the supplied func fo reach domain
Description

Use this method to safely iterate over all the loaded application domains in the current runtime. The provided func is invoked with a pointer to the MonoDomain and is given the value of the user_data parameter which can be used to pass state to your called routine.

mono_domain_free
Syntax
void mono_domain_free (MonoDomain *domain, gboolean force)

Parameters
domain the domain to release
force if TRUE, it allows the root domain to be released (used at shutdown only).
Description

This releases the resources associated with the specific domain. This is a low-level function that is invoked by the AppDomain infrastructure when necessary.

mono_domain_from_appdomain
Syntax
MonoDomain* mono_domain_from_appdomain (MonoAppDomain *appdomain_raw)

mono_domain_get_by_id
Syntax
MonoDomain* mono_domain_get_by_id (gint32 domainid)

Parameters
domainid the ID
Return value
the domain for a specific domain id.
mono_domain_get_friendly_name
Syntax
const char * mono_domain_get_friendly_name (MonoDomain *domain)

Return value
The friendly name of domain. Can be NULL if not yet set.
Description

The returned string's lifetime is the same as domain's. Consider copying it if you need to store it somewhere.

mono_domain_get_id
Syntax
gint32 mono_domain_get_id (MonoDomain *domain)

Return value
The unique ID for domain.
Description

A domain ID is guaranteed to be unique for as long as the domain using it is alive. It may be reused later once the domain has been unloaded.

mono_domain_get
Syntax
MonoDomain* mono_domain_get ()

Return value
the current domain
Description

This method returns the value of the current MonoDomain that this thread and code are running under. To obtain the root domain use mono_get_root_domain API.

mono_domain_has_type_resolve
Syntax
gboolean mono_domain_has_type_resolve (MonoDomain *domain)

Parameters
domain application domain being looked up
Return value
TRUE if the AppDomain.TypeResolve field has been set.
Description

mono_domain_is_unloading
Syntax
gboolean mono_domain_is_unloading (MonoDomain *domain)

mono_domain_owns_vtable_slot
Syntax
gboolean mono_domain_owns_vtable_slot (MonoDomain *domain, gpointer vtable_slot)

Return value
Whether vtable_slot is inside a vtable which belongs to domain.
mono_domain_set_config
Syntax
void mono_domain_set_config (MonoDomain *domain, const char *base_dir, const char *config_file_name)

Parameters
domain MonoDomain initialized with the appdomain we want to change
base_dir new base directory for the appdomain
config_file_name path to the new configuration for the app domain
Description

Used to set the system configuration for an appdomain

Without using this, embedded builds will get 'System.Configuration.ConfigurationErrorsException: Error Initializing the configuration system. ---> System.ArgumentException: The 'ExeConfigFilename' argument cannot be null.' for some managed calls.

mono_domain_set_internal
Syntax
void mono_domain_set_internal (MonoDomain *domain)

Parameters
domain the new domain
Description

Sets the current domain to domain.

mono_domain_set
Syntax
gboolean mono_domain_set (MonoDomain *domain, gboolean force)

Parameters
domain domain
force force setting.
Return value
TRUE on success; FALSE if the domain is unloaded
Description

Set the current appdomain to domain. If force is set, set it even if it is being unloaded.

mono_domain_try_type_resolve
Syntax
MonoReflectionAssembly* mono_domain_try_type_resolve (MonoDomain *domain, char *name, MonoObject *tb)

Parameters
domain application domainwhere the name where the type is going to be resolved
name the name of the type to resolve or NULL.
tb A System.Reflection.Emit.TypeBuilder, used if name is NULL.
Return value
A MonoReflectionAssembly or NULL if not found
Description

This routine invokes the internal System.AppDomain.DoTypeResolve and returns the assembly that matches name.

If name is null, the value of ((TypeBuilder)tb).FullName is used instead

mono_domain_try_unload
Syntax
mono_domain_try_unload

mono_domain_unload
Syntax
void mono_domain_try_unload (MonoDomain *domain, MonoObject **exc)

Parameters
domain The domain to unload
exc Exception information
Description

Unloads an appdomain. Follows the process outlined in: http://blogs.gotdotnet.com/cbrumme

If doing things the 'right' way is too hard or complex, we do it the 'simple' way, which means do everything needed to avoid crashes and memory leaks, but not much else.

It is required to pass a valid reference to the exc argument, upon return from this function *exc will be set to the exception thrown, if any.

If this method is not called from an icall (embedded scenario for instance), it must not be called with any managed frames on the stack, since the unload process could end up trying to abort the current thread.

Contexts

mono_context_init
Syntax
void mono_context_init (MonoDomain *domain)

Parameters
domain The domain where the System.Runtime.Remoting.Context.Context is initialized
Description
Initializes the domain's default System.Runtime.Remoting 's Context.
mono_context_get
Syntax
MonoAppContext* mono_context_get (void)

Return value
the current Mono Application Context.
Description

mono_context_get_domain_id
Syntax
gint32 mono_context_get_domain_id (MonoAppContext *context)

Parameters
context the context to operate on.
Return value
The ID of the domain that context was created in.
mono_context_get_id
Syntax
gint32 mono_context_get_id (MonoAppContext *context)

Parameters
context the context to operate on.
Return value
The unique ID for context.
Description

Context IDs are guaranteed to be unique for the duration of a Mono process; they are never reused.

mono_context_set
Syntax
void mono_context_set (MonoAppContext * new_context)