README.md

Reentrant OCaml

This branch is the first step towards multicore support in OCaml. The
reentrant runtime allows multiple runtimes to run independantly in the
same process, typically one per core on multicore machines, enabling
parallel computation. Each runtime can have many threads associated,
but threads do not run in parallel on each single runtime. This
enables us to keep the current OCaml garbage collector, which is
extremely efficient in the sequential case, essentially as it is.

Different runtimes can exchange messages using send and receive
primitives on shared mailboxes.

The feature is also useful when multiple runtimes are exposed as C
libraries.

Status

DONE

Most static variables of the runtime have been moved into the context

Most C functions of the runtime have been renamed to _r(CAML_R, to take
as first parameter the runtime context containing all former static variables.

External functions in OCaml can now be declared as "reentrant", i.e. receiving
the context as first parameter.

The AMD64 backend of ocamlopt has been updated to use the runtime context and
provide it to reentrant external functions.

The bytecode interpreter now also uses the context data structure, and can be used
for parallel programming.

C functions in unix, str, bigarray have been updated, static variables have been moved
into library specific contexts.

Fixed otherlibs/systhreads, to allow each runtime to have many (non-parallel) threads
associated.

IN PROGRESS

Fixing otherlibs/threads, to add multi-threading-over-multi-context support to
bytecode

TODO

Only the AMD64 backend has been implemented. Implement the other ones.

Only TLS (Thread Local Storage) is currenty supported.

At the end, we need to provide all the functions that were renamed in _r in
their older format, for backward compatibility.

Update the rest of C functions in otherlibs/

Principles

Each function in the runtime takes as first argument a "runtime
context", containing all the variables that used to be static. To
decrease the size of the patch, the file context.h defines for each
variable a macro that lookup the variable within the context. All
these functions have a suffix _r, and the macro CAML_R defines their
first argument.

Once all functions will have been rewritten like that, we should
implement the former version (without the first argument) by looking
up the context in the thread local storage, using the function
"caml_get_thread_local_context()".

Since we needed a global lock for all the runtimes, it has been
implemented as "caml_enter_blocking_section()" (which should still be
used for exclusion within a given runtime), by introducing two
functions "caml_enter_lock_section()" and
"caml_leave_lock_section()". These functions don't do anything right
now, but locking should be added within the thread libraries by
redefining "caml_enter_lock_section_hook" and
"caml_leave_lock_section_hook". [FIXME: these names are very
counterintuitive. Why do we have to name "caml_enter_lock_section"
and "caml_enter_blocking_section" so similarly? --Luca Saiu. The name
"caml_enter_lock_section" was terrible to begin with: see
http://d.hatena.ne.jp/camlspotter/20100309/1268111257 ]

For static variables within libraries, the library should define its
own runtime context, and use "caml_get_library_context_r(...)" to
access it. Such contexts are currently limited to 24
(MAX_OTHER_CONTEXTS), but the limitation should be removed soon.