1 /**************************************************************************/
2 /* */
3 /* OCaml */
4 /* */
5 /* Xavier Leroy and Damien Doligez, INRIA Rocquencourt */
6 /* */
7 /* Copyright 1995 Institut National de Recherche en Informatique et */
8 /* en Automatique. */
9 /* */
10 /* All rights reserved. This file is distributed under the terms of */
11 /* the GNU Lesser General Public License version 2.1, with the */
12 /* special exception on linking described in the file LICENSE. */
13 /* */
14 /**************************************************************************/
15
16 #ifndef CAML_THREADS_H
17 #define CAML_THREADS_H
18
19 #ifdef __cplusplus
20 extern "C" {
21 #endif
22
23 CAMLextern void caml_enter_blocking_section (void);
24 CAMLextern void caml_leave_blocking_section (void);
25 #define caml_acquire_runtime_system caml_leave_blocking_section
26 #define caml_release_runtime_system caml_enter_blocking_section
27
28 /* Manage the master lock around the OCaml run-time system.
29 Only one thread at a time can execute OCaml compiled code or
30 OCaml run-time system functions.
31
32 When OCaml calls a C function, the current thread holds the master
33 lock. The C function can release it by calling
34 [caml_release_runtime_system]. Then, another thread can execute OCaml
35 code. However, the calling thread must not access any OCaml data,
36 nor call any runtime system function, nor call back into OCaml.
37
38 Before returning to its OCaml caller, or accessing OCaml data,
39 or call runtime system functions, the current thread must
40 re-acquire the master lock by calling [caml_acquire_runtime_system].
41
42 Symmetrically, if a C function (not called from OCaml) wishes to
43 call back into OCaml code, it should invoke [caml_acquire_runtime_system]
44 first, then do the callback, then invoke [caml_release_runtime_system].
45
46 For historical reasons, alternate names can be used:
47 [caml_enter_blocking_section] instead of [caml_release_runtime_system]
48 [caml_leave_blocking_section] instead of [caml_acquire_runtime_system]
49 Intuition: a ``blocking section'' is a piece of C code that does not
50 use the runtime system (typically, a blocking I/O operation).
51 */
52
53 CAMLextern int caml_c_thread_register(void);
54 CAMLextern int caml_c_thread_unregister(void);
55
56 /* If a thread is created by C code (instead of by OCaml itself),
57 it must be registered with the OCaml runtime system before
58 being able to call back into OCaml code or use other runtime system
59 functions. Just call [caml_c_thread_register] once.
60 Before the thread finishes, it must call [caml_c_thread_unregister].
61 Both functions return 1 on success, 0 on error.
62 */
63
64 #ifdef __cplusplus
65 }
66 #endif
67
68 #endif /* CAML_THREADS_H */
69