1Thread(3)                        OCaml library                       Thread(3)
2
3
4

NAME

6       Thread - Lightweight threads for Posix 1003.1c and Win32.
7

Module

9       Module   Thread
10

Documentation

12       Module Thread
13        : sig end
14
15
16       Lightweight threads for Posix 1003.1c and Win32.
17
18
19
20
21
22       type t
23
24
25       The type of thread handles.
26
27
28
29
30   Thread creation and termination
31       val create : ('a -> 'b) -> 'a -> t
32
33
34       Thread.create  funct  arg creates a new thread of control, in which the
35       function application funct arg is executed concurrently with the  other
36       threads  of  the  domain.  The application of Thread.create returns the
37       handle of the newly created thread.  The new thread terminates when the
38       application  funct  arg  returns,  either  normally  or  by raising the
39       Thread.Exit exception or by raising any other uncaught  exception.   In
40       the last case, the uncaught exception is printed on standard error, but
41       not propagated back to the parent thread. Similarly, the result of  the
42       application  funct  arg is discarded and not directly accessible to the
43       parent thread.
44
45       See also Domain.spawn if you want parallel execution instead.
46
47
48
49       val self : unit -> t
50
51       Return the handle for the thread currently executing.
52
53
54
55       val id : t -> int
56
57       Return the identifier of the given thread. A thread  identifier  is  an
58       integer  that  identifies uniquely the thread.  It can be used to build
59       data structures indexed by threads.
60
61
62
63       exception Exit
64
65
66       Exception raised by user code to initiate termination  of  the  current
67       thread.   In  a  thread  created  by  Thread.create  funct arg , if the
68       Thread.Exit exception reaches the top of the application funct arg , it
69       has  the  effect  of terminating the current thread silently.  In other
70       contexts, there is no implicit handling of the Thread.Exit exception.
71
72
73
74       val exit : unit -> unit
75
76       Deprecated.  Use 'raise Thread.Exit' instead.
77
78
79       Raise the Thread.Exit exception.  In a thread created by  Thread.create
80       ,  this  will  cause  the  thread  to terminate prematurely, unless the
81       thread function handles the exception itself.   Fun.protect  finalizers
82       and catch-all exception handlers will be executed.
83
84       To  make it clear that an exception is raised and will trigger finaliz‐
85       ers and catch-all exception handlers, it is recommended to write  raise
86       Thread.Exit instead of Thread.exit () .
87
88
89       Before5.0  A different implementation was used, not based on raising an
90       exception, and not running finalizers and catch-all handlers.  The pre‐
91       vious  implementation had a different behavior when called outside of a
92       thread created by Thread.create .
93
94
95
96
97
98   Suspending threads
99       val delay : float -> unit
100
101
102       delay d suspends the execution of the calling thread for d seconds. The
103       other program threads continue to run during this time.
104
105
106
107       val join : t -> unit
108
109
110       join  th  suspends the execution of the calling thread until the thread
111       th has terminated.
112
113
114
115       val yield : unit -> unit
116
117       Re-schedule the calling thread without suspending  it.   This  function
118       can be used to give scheduling hints, telling the scheduler that now is
119       a good time to switch to other threads.
120
121
122
123
124   Waiting for file descriptors or processes
125       The functions below are leftovers from an earlier,  VM-based  threading
126       system.   The  Unix module provides equivalent functionality, in a more
127       general and more standard-conformant manner.  It is recommended to  use
128       Unix functions directly.
129
130       val wait_timed_read : Unix.file_descr -> float -> bool
131
132       Deprecated.  Use Unix.select instead.
133
134
135       See Thread.wait_timed_write .
136
137
138
139       val wait_timed_write : Unix.file_descr -> float -> bool
140
141       Deprecated.  Use Unix.select instead.
142
143
144       Suspend  the execution of the calling thread until at least one charac‐
145       ter or EOF is available for reading ( wait_timed_read ) or one  charac‐
146       ter  can  be written without blocking ( wait_timed_write ) on the given
147       Unix file descriptor. Wait for at most the amount of time given as sec‐
148       ond argument (in seconds).  Return true if the file descriptor is ready
149       for input/output and false if the timeout expired.  The same  function‐
150       ality can be achieved with Unix.select .
151
152
153
154       val   select   :   Unix.file_descr  list  ->  Unix.file_descr  list  ->
155       Unix.file_descr list -> float -> Unix.file_descr list * Unix.file_descr
156       list * Unix.file_descr list
157
158       Deprecated.  Use Unix.select instead.
159
160
161       Same  function  as  Unix.select .  Suspend the execution of the calling
162       thread until input/output becomes possible on the given Unix  file  de‐
163       scriptors.   The  arguments  and  results  have the same meaning as for
164       Unix.select .
165
166
167
168       val wait_pid : int -> int * Unix.process_status
169
170       Deprecated.  Use Unix.waitpid instead.
171
172
173       Same function as Unix.waitpid .  wait_pid p suspends the  execution  of
174       the  calling  thread until the process specified by the process identi‐
175       fier p terminates. Returns the pid of the child caught and its termina‐
176       tion status, as per Unix.wait .
177
178
179
180
181   Management of signals
182       Signal  handling follows the POSIX thread model: signals generated by a
183       thread are delivered to that thread; signals generated  externally  are
184       delivered  to  one  of the threads that does not block it.  Each thread
185       possesses a set  of  blocked  signals,  which  can  be  modified  using
186       Thread.sigmask  .   This  set  is  inherited  at  thread creation time.
187       Per-thread signal masks are supported only by the system thread library
188       under Unix, but not under Win32, nor by the VM thread library.
189
190       val sigmask : Unix.sigprocmask_command -> int list -> int list
191
192
193       sigmask  cmd  sigs  changes  the set of blocked signals for the calling
194       thread.  If cmd is SIG_SETMASK , blocked signals are set  to  those  in
195       the list sigs .  If cmd is SIG_BLOCK , the signals in sigs are added to
196       the set of blocked signals.  If cmd is SIG_UNBLOCK  ,  the  signals  in
197       sigs  are removed from the set of blocked signals.  sigmask returns the
198       set of previously blocked signals for the thread.
199
200
201
202       val wait_signal : int list -> int
203
204
205       wait_signal sigs suspends the execution of the calling thread until the
206       process  receives  one  of the signals specified in the list sigs .  It
207       then returns the number of the signal received.   Signal  handlers  at‐
208       tached  to  the  signals in sigs will not be invoked.  The signals sigs
209       are expected to be blocked before calling wait_signal .
210
211
212
213
214   Uncaught exceptions
215       val default_uncaught_exception_handler : exn -> unit
216
217
218       Thread.default_uncaught_exception_handler will print the  thread's  id,
219       exception and backtrace (if available).
220
221
222
223       val set_uncaught_exception_handler : (exn -> unit) -> unit
224
225
226       Thread.set_uncaught_exception_handler  fn  registers  fn as the handler
227       for uncaught exceptions.
228
229       If the  newly  set  uncaught  exception  handler  raise  an  exception,
230       Thread.default_uncaught_exception_handler will be called.
231
232
233
234
235
236OCamldoc                          2023-07-20                         Thread(3)