2004-06-03 Atsushi Enomoto <atsushi@ximian.com>

[mono.git] / docs / embedded-api

diff --git a/docs/embedded-api b/docs/embedded-api
index f943b8ffbf95780379b2a28ffd39095e75a0b927..1fd739ae2ba82eda4fbb23486982cd6fabf74f7d 100644 (file)
--- a/docs/embedded-api
+++ b/docs/embedded-api
@@ -1,11 +1,13 @@
        
           Embedding the Mono runtime, preliminary version
-
-                   Miguel de Icaza, Paolo Molaro.
+                Miguel de Icaza (miguel@ximian.com),
+                  Paolo Molaro (lupus@ximian.com)
 
        This document describes how to embed the Mono runtime in your
        application, and how to invoke CIL methods from C, and how to
-       invoke C code from CIL.
+       invoke C code from CIL. Both the JIT and interpreter can be
+       embedded in very similar ways so most of what is described
+       here can be used in either case.
 
 * Embedding the runtime.
 
@@ -27,6 +29,12 @@
 
                pkg-config --cflags --libs mono
 
+       is used to get the flags for the JIT runtime and
+
+               pkg-config --cflags --libs mint
+
+       for the interpreted runtime.
+
        Like this:
 
                gcc sample.c `pkg-config --cflags --libs mono`
@@ -39,12 +47,22 @@
 
 ** Initializing the Mono runtime
 
-       To initialize the runtime, call mono_jit_init, like this:
+       To initialize the JIT runtime, call mono_jit_init, like this:
+
+               #include <mono/mini/jit.h>
 
                MonoDomain *domain;
 
                domain = mono_jit_init ("domain-name");
 
+       For the interpreted runtime use mono_interp_init instead:
+
+               #include <mono/interpreter/embed.h>
+
+               MonoDomain *domain;
+
+               domain = mono_interp_init ("domain-name");
+
        That will return a MonoDomain where your code will be
        executed.  You can create multiple domains.  Each domain is
        isolated from the other domains and code in one domain will
@@ -55,7 +73,7 @@
 
                MonoAssembly *assembly;
 
-               assembly = mono_domain_assembly_open ("file.dll");
+               assembly = mono_domain_assembly_open (domain, "file.dll");
                if (!assembly)
                        error ();
 
@@ -70,6 +88,10 @@
 
                retval = mono_jit_exec (domain, assembly, argc - 1, argv + 1);
 
+       or when using the interpreter use:
+
+               retval = mono_interp_exec (domain, assembly, argc - 1, argv + 1);
+
        If you want to invoke a different method, look at the
        `Invoking Methods in the CIL universe' section later on.
 
@@ -80,6 +102,10 @@
 
                mono_jit_cleanup (domain);
 
+       Or in the case of the interpreted runtime use:
+
+               mono_interp_cleanup (domain);
+
 ** Applications that use threads.
 
        The Boehm GC system needs to catch your calls to the pthreads
@@ -183,6 +209,9 @@
        methods, a MonoObject* for object instances and a pointer to
        the value type for value types.
 
+       These functions can be used in both the JIT and the interpreted
+       environments.
+
        The params array contains the arguments to the method with the
        same convention: MonoObject* pointers for object instances and
        pointers to the value type otherwise. The _invoke_array
@@ -225,9 +254,18 @@
        It may not be possible to manage exceptions in that case,
        though. I need to think more about it.
 
+** Threading issues
+
+       If your application creates threads on its own, and you want them to 
+       be able to call code into the CIL universe with Mono, you have to
+       register the thread with Mono before issuing the call.
+
+       To do so, call the mono_thread_attach() function before you execute
+       any managed code from the thread
+
 * Samples
 
-       See the sample programs inmono/sample/embed for examples of
+       See the sample programs in mono/sample/embed for examples of
        embedding the Mono runtime in your application.