134 lines | 5894 chars
1 | (**************************************************************************) |
2 | (* *) |
3 | (* OCaml *) |
4 | (* *) |
5 | (* Xavier Leroy and Pascal Cuoq, projet Cristal, 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 | (** Lightweight threads for Posix [1003.1c] and Win32. *) |
17 | |
18 | type t |
19 | (** The type of thread handles. *) |
20 | |
21 | (** {1 Thread creation and termination} *) |
22 | |
23 | val create : ('a -> 'b) -> 'a -> t |
24 | (** [Thread.create funct arg] creates a new thread of control, |
25 | in which the function application [funct arg] |
26 | is executed concurrently with the other threads of the program. |
27 | The application of [Thread.create] |
28 | returns the handle of the newly created thread. |
29 | The new thread terminates when the application [funct arg] |
30 | returns, either normally or by raising an uncaught exception. |
31 | In the latter case, the exception is printed on standard error, |
32 | but not propagated back to the parent thread. Similarly, the |
33 | result of the application [funct arg] is discarded and not |
34 | directly accessible to the parent thread. *) |
35 | |
36 | val self : unit -> t |
37 | (** Return the thread currently executing. *) |
38 | |
39 | val id : t -> int |
40 | (** Return the identifier of the given thread. A thread identifier |
41 | is an integer that identifies uniquely the thread. |
42 | It can be used to build data structures indexed by threads. *) |
43 | |
44 | val exit : unit -> unit |
45 | (** Terminate prematurely the currently executing thread. *) |
46 | |
47 | val kill : t -> unit |
48 | (** Terminate prematurely the thread whose handle is given. *) |
49 | |
50 | (** {1 Suspending threads} *) |
51 | |
52 | val delay: float -> unit |
53 | (** [delay d] suspends the execution of the calling thread for |
54 | [d] seconds. The other program threads continue to run during |
55 | this time. *) |
56 | |
57 | val join : t -> unit |
58 | (** [join th] suspends the execution of the calling thread |
59 | until the thread [th] has terminated. *) |
60 | |
61 | val wait_read : Unix.file_descr -> unit |
62 | (** See {!Thread.wait_write}.*) |
63 | |
64 | val wait_write : Unix.file_descr -> unit |
65 | (** This function does nothing in this implementation. *) |
66 | |
67 | val wait_timed_read : Unix.file_descr -> float -> bool |
68 | (** See {!Thread.wait_timed_write}.*) |
69 | |
70 | val wait_timed_write : Unix.file_descr -> float -> bool |
71 | (** Suspend the execution of the calling thread until at least |
72 | one character or EOF is available for reading ([wait_read]) or |
73 | one character can be written without blocking ([wait_write]) |
74 | on the given Unix file descriptor. Wait for at most |
75 | the amount of time given as second argument (in seconds). |
76 | Return [true] if the file descriptor is ready for input/output |
77 | and [false] if the timeout expired. |
78 | |
79 | These functions return immediately [true] in the Win32 |
80 | implementation. *) |
81 | |
82 | val select : |
83 | Unix.file_descr list -> Unix.file_descr list -> |
84 | Unix.file_descr list -> float -> |
85 | Unix.file_descr list * Unix.file_descr list * Unix.file_descr list |
86 | (** Suspend the execution of the calling thread until input/output |
87 | becomes possible on the given Unix file descriptors. |
88 | The arguments and results have the same meaning as for |
89 | [Unix.select]. |
90 | This function is not implemented yet under Win32. *) |
91 | |
92 | val wait_pid : int -> int * Unix.process_status |
93 | (** [wait_pid p] suspends the execution of the calling thread |
94 | until the process specified by the process identifier [p] |
95 | terminates. Returns the pid of the child caught and |
96 | its termination status, as per [Unix.wait]. |
97 | This function is not implemented under MacOS. *) |
98 | |
99 | val yield : unit -> unit |
100 | (** Re-schedule the calling thread without suspending it. |
101 | This function can be used to give scheduling hints, |
102 | telling the scheduler that now is a good time to |
103 | switch to other threads. *) |
104 | |
105 | (** {1 Management of signals} *) |
106 | |
107 | (** Signal handling follows the POSIX thread model: signals generated |
108 | by a thread are delivered to that thread; signals generated externally |
109 | are delivered to one of the threads that does not block it. |
110 | Each thread possesses a set of blocked signals, which can be modified |
111 | using {!Thread.sigmask}. This set is inherited at thread creation time. |
112 | Per-thread signal masks are supported only by the system thread library |
113 | under Unix, but not under Win32, nor by the VM thread library. *) |
114 | |
115 | val sigmask : Unix.sigprocmask_command -> int list -> int list |
116 | (** [sigmask cmd sigs] changes the set of blocked signals for the |
117 | calling thread. |
118 | If [cmd] is [SIG_SETMASK], blocked signals are set to those in |
119 | the list [sigs]. |
120 | If [cmd] is [SIG_BLOCK], the signals in [sigs] are added to |
121 | the set of blocked signals. |
122 | If [cmd] is [SIG_UNBLOCK], the signals in [sigs] are removed |
123 | from the set of blocked signals. |
124 | [sigmask] returns the set of previously blocked signals for the thread. *) |
125 | |
126 | |
127 | val wait_signal : int list -> int |
128 | (** [wait_signal sigs] suspends the execution of the calling thread |
129 | until the process receives one of the signals specified in the |
130 | list [sigs]. It then returns the number of the signal received. |
131 | Signal handlers attached to the signals in [sigs] will not |
132 | be invoked. The signals [sigs] are expected to be blocked before |
133 | calling [wait_signal]. *) |
134 |