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 program.  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
46
47       val self : unit -> t
48
49       Return the handle for the thread currently executing.
50
51
52
53       val id : t -> int
54
55       Return the identifier of the given thread. A thread  identifier  is  an
56       integer  that  identifies uniquely the thread.  It can be used to build
57       data structures indexed by threads.
58
59
60
61       exception Exit
62
63
64       Exception that can be raised by user code to  initiate  termination  of
65       the  current  thread.   Compared  to  calling the Thread.exit function,
66       raising the Thread.Exit exception will trigger  Fun.finally  finalizers
67       and  catch-all exception handlers.  It is the recommended way to termi‐
68       nate threads prematurely.
69
70
71       Since 4.14.0
72
73
74
75       val exit : unit -> unit
76
77       Terminate prematurely the currently executing thread.
78
79
80
81       val kill : t -> unit
82
83       This function was supposed to terminate prematurely  the  thread  whose
84       handle  is given.  It is not currently implemented due to problems with
85       cleanup handlers on many  POSIX  1003.1c  implementations.   It  always
86       raises the Invalid_argument exception.
87
88
89
90
91   Suspending threads
92       val delay : float -> unit
93
94
95       delay d suspends the execution of the calling thread for d seconds. The
96       other program threads continue to run during this time.
97
98
99
100       val join : t -> unit
101
102
103       join th suspends the execution of the calling thread until  the  thread
104       th has terminated.
105
106
107
108       val yield : unit -> unit
109
110       Re-schedule  the  calling  thread without suspending it.  This function
111       can be used to give scheduling hints, telling the scheduler that now is
112       a good time to switch to other threads.
113
114
115
116
117   Waiting for file descriptors or processes
118       The  functions  below are leftovers from an earlier, VM-based threading
119       system.  The Unix module provides equivalent functionality, in  a  more
120       general  and more standard-conformant manner.  It is recommended to use
121       Unix functions directly.
122
123       val wait_read : Unix.file_descr -> unit
124
125       This function does nothing in the current implementation of the thread‐
126       ing library and can be removed from all user programs.
127
128
129
130       val wait_write : Unix.file_descr -> unit
131
132       This function does nothing in the current implementation of the thread‐
133       ing library and can be removed from all user programs.
134
135
136
137       val wait_timed_read : Unix.file_descr -> float -> bool
138
139       See Thread.wait_timed_write .
140
141
142
143       val wait_timed_write : Unix.file_descr -> float -> bool
144
145       Suspend the execution of the calling thread until at least one  charac‐
146       ter  or EOF is available for reading ( wait_timed_read ) or one charac‐
147       ter can be written without blocking ( wait_timed_write ) on  the  given
148       Unix file descriptor. Wait for at most the amount of time given as sec‐
149       ond argument (in seconds).  Return true if the file descriptor is ready
150       for  input/output and false if the timeout expired.  The same function‐
151       ality can be achieved with Unix.select .
152
153
154
155       val  select  :  Unix.file_descr  list  ->   Unix.file_descr   list   ->
156       Unix.file_descr list -> float -> Unix.file_descr list * Unix.file_descr
157       list * Unix.file_descr list
158
159       Same function as Unix.select .  Suspend the execution  of  the  calling
160       thread  until  input/output becomes possible on the given Unix file de‐
161       scriptors.  The arguments and results have  the  same  meaning  as  for
162       Unix.select .
163
164
165
166       val wait_pid : int -> int * Unix.process_status
167
168       Same  function  as Unix.waitpid .  wait_pid p suspends the execution of
169       the calling thread until the process specified by the  process  identi‐
170       fier p terminates. Returns the pid of the child caught and its termina‐
171       tion status, as per Unix.wait .
172
173
174
175
176   Management of signals
177       Signal handling follows the POSIX thread model: signals generated by  a
178       thread  are  delivered to that thread; signals generated externally are
179       delivered to one of the threads that does not block  it.   Each  thread
180       possesses  a  set  of  blocked  signals,  which  can  be modified using
181       Thread.sigmask .  This  set  is  inherited  at  thread  creation  time.
182       Per-thread signal masks are supported only by the system thread library
183       under Unix, but not under Win32, nor by the VM thread library.
184
185       val sigmask : Unix.sigprocmask_command -> int list -> int list
186
187
188       sigmask cmd sigs changes the set of blocked  signals  for  the  calling
189       thread.   If  cmd  is SIG_SETMASK , blocked signals are set to those in
190       the list sigs .  If cmd is SIG_BLOCK , the signals in sigs are added to
191       the  set  of  blocked  signals.  If cmd is SIG_UNBLOCK , the signals in
192       sigs are removed from the set of blocked signals.  sigmask returns  the
193       set of previously blocked signals for the thread.
194
195
196
197       val wait_signal : int list -> int
198
199
200       wait_signal sigs suspends the execution of the calling thread until the
201       process receives one of the signals specified in the list  sigs  .   It
202       then  returns  the  number of the signal received.  Signal handlers at‐
203       tached to the signals in sigs will not be invoked.   The  signals  sigs
204       are expected to be blocked before calling wait_signal .
205
206
207
208
209   Uncaught exceptions
210       val default_uncaught_exception_handler : exn -> unit
211
212
213       Thread.default_uncaught_exception_handler  will  print the thread's id,
214       exception and backtrace (if available).
215
216
217
218       val set_uncaught_exception_handler : (exn -> unit) -> unit
219
220
221       Thread.set_uncaught_exception_handler fn registers fn  as  the  handler
222       for uncaught exceptions.
223
224       If  the  newly  set  uncaught  exception  handler  raise  an exception,
225       Thread.default_uncaught_exception_handler will be called.
226
227
228
229
230
231OCamldoc                          2023-01-23                         Thread(3)