File: manual063.html

package info (click to toggle)
ocaml-doc 2.04-2
links: PTS
area: main
in suites: potato
size: 2,820 kB
ctags: 997
sloc: makefile: 38; sh: 12
file content (494 lines) | stat: -rw-r--r-- 18,822 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset= ISO-8859-1">
<TITLE>
 The threads library
</TITLE>
</HEAD>
<BODY >
<A HREF="manual062.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="manual064.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
<HR>

<H1>Chapter&nbsp;21:&nbsp;&nbsp; The threads library</H1>
<A NAME="c:threads"></A>
The <TT>threads</TT> library allows concurrent programming in Objective Caml.
It provides multiple threads of control (also called lightweight
processes) that execute concurrently in the same memory space. Threads
communicate by in-place modification of shared data structures, or by
sending and receiving data on communication channels.<BR>
<BR>
The <TT>threads</TT> library is implemented by time-sharing on a single
processor. It will not take advantage of multi-processor machines.
Using this library will therefore never make programs run
faster. However, many programs are easier to write when structured as
several communicating processes.<BR>
<BR>

&nbsp;&nbsp;<FONT COLOR=purple>Unix:</FONT>
<BLOCKQUOTE>
Programs that use the <TT>threads</TT> library must be linked as follows:
<PRE>
        ocamlc -thread -custom <I>other options</I> threads.cma <I>other files</I> -cclib -lthreads
</PRE>
The <TT>-thread</TT> option selects a special, thread-safe version of
the standard library (see chapter&nbsp;<A HREF="manual020.html#c:camlc">7</A>). The <TT>-thread</TT>
option must also be given when compiling any source file that
references modules from the thread library (<TT>Thread</TT>, <TT>Mutex</TT>, ...).<BR>
<BR>
The default thread implementation cannot be used in native-code
programs compiled with <TT>ocamlopt</TT>. If your operating system provides
POSIX 1003.1c compliant threads, you can select an alternate
implementation when configuring Objective Caml (use the
<TT>-with-pthread</TT> option to <TT>configure</TT>) which also supports native-code
programs. Programs that use this alternate implementation of the
<TT>threads</TT> library must be linked as follows:
<PRE>
        ocamlc -thread -custom <I>other options</I> threads.cma <I>other files</I> \
                 -cclib -lthreads -cclib -lunix -cclib -lpthread
        ocamlopt -thread <I>other options</I> threads.cmxa <I>other files</I> \
                -cclib -lthreadsnat -cclib -lunix -cclib -lpthread
</PRE>
Depending on the operating system, extra system libraries can be
necessary. For instance, under Solaris 2.5, add <TT>-cclib -lposix4</TT>
at the end of the command line.
</BLOCKQUOTE>
&nbsp;&nbsp;<FONT COLOR=purple>Windows:</FONT>
<BLOCKQUOTE>
Programs that use the <TT>threads</TT> library must be linked as follows:
<PRE>
        ocamlc -thread -custom <I>other options</I> threads.cma <I>other files</I> -cclib -lthreads
</PRE>
All object files on the command line must also have been compiled with
the <TT>-thread</TT> option, which selects a special, thread-safe version of
the standard library (see chapter&nbsp;<A HREF="manual020.html#c:camlc">7</A>).
</BLOCKQUOTE>

<H2>21.1&nbsp;&nbsp; Module <TT>Thread</TT>: lightweight threads</H2><A NAME="s:Thread"></A>
<A NAME="@manual765"></A><PRE>
type t
</PRE>
<BLOCKQUOTE>
The type of thread handles. 
</BLOCKQUOTE>

<H4>Thread creation and termination </H4>
<PRE>
val create : ('a -&gt; 'b) -&gt; 'a -&gt; t
</PRE>
<A NAME="@manual766"></A><BLOCKQUOTE>
<CODE>Thread.create funct arg</CODE> creates a new thread of control,
in which the function application <CODE>funct arg</CODE>
is executed concurrently with the other threads of the program.
The application of <CODE>Thread.create</CODE>
returns the handle of the newly created thread.
The new thread terminates when the application <CODE>funct arg</CODE>
returns, either normally or by raising an uncaught exception.
In the latter case, the exception is printed on standard error,
but not propagated back to the parent thread. Similarly, the
result of the application <CODE>funct arg</CODE> is discarded and not
directly accessible to the parent thread. 
</BLOCKQUOTE>
<PRE>
val self : unit -&gt; t
</PRE>
<A NAME="@manual767"></A><BLOCKQUOTE>
Return the thread currently executing. 
</BLOCKQUOTE>
<PRE>
val id : t -&gt; int
</PRE>
<A NAME="@manual768"></A><BLOCKQUOTE>
Return the identifier of the given thread. A thread identifier
is an integer that identifies uniquely the thread.
It can be used to build data structures indexed by threads. 
</BLOCKQUOTE>
<PRE>
val exit : unit -&gt; unit
</PRE>
<A NAME="@manual769"></A><BLOCKQUOTE>
Terminate prematurely the currently executing thread. 
</BLOCKQUOTE>
<PRE>
val kill : t -&gt; unit
</PRE>
<A NAME="@manual770"></A><BLOCKQUOTE>
Terminate prematurely the thread whose handle is given.
This functionality is available only with bytecode-level threads. 
</BLOCKQUOTE>

<H4>Suspending threads </H4>
<PRE>
val delay: float -&gt; unit
</PRE>
<A NAME="@manual771"></A><BLOCKQUOTE>
<CODE>delay d</CODE> suspends the execution of the calling thread for
<CODE>d</CODE> seconds. The other program threads continue to run during
this time. 
</BLOCKQUOTE>
<PRE>
val join : t -&gt; unit
</PRE>
<A NAME="@manual772"></A><BLOCKQUOTE>
<CODE>join th</CODE> suspends the execution of the calling thread
until the thread <CODE>th</CODE> has terminated. 
</BLOCKQUOTE>
<PRE>
val wait_read : Unix.file_descr -&gt; unit
val wait_write : Unix.file_descr -&gt; unit
</PRE>
<A NAME="@manual773"></A><A NAME="@manual774"></A><BLOCKQUOTE>
Suspend the execution of the calling thread until at least
one character is available for reading (<CODE>wait_read</CODE>) or
one character can be written without blocking (<CODE>wait_write</CODE>)
on the given Unix file descriptor. 
</BLOCKQUOTE>
<PRE>
val wait_timed_read : Unix.file_descr -&gt; float -&gt; bool
val wait_timed_write : Unix.file_descr -&gt; float -&gt; bool
</PRE>
<A NAME="@manual775"></A><A NAME="@manual776"></A><BLOCKQUOTE>
Same as <CODE>wait_read</CODE> and <CODE>wait_write</CODE>, but wait for at most
the amount of time given as second argument (in seconds).
Return <CODE>true</CODE> if the file descriptor is ready for input/output
and <CODE>false</CODE> if the timeout expired. 
</BLOCKQUOTE>
<PRE>
val select :
  Unix.file_descr list -&gt; Unix.file_descr list -&gt;
  Unix.file_descr list -&gt; float -&gt;
    Unix.file_descr list * Unix.file_descr list * Unix.file_descr list
</PRE>
<A NAME="@manual777"></A><BLOCKQUOTE>
Suspend the execution of the calling thead until input/output
becomes possible on the given Unix file descriptors.
The arguments and results have the same meaning as for
<CODE>Unix.select</CODE>. 
</BLOCKQUOTE>
<PRE>
val wait_pid : int -&gt; int * Unix.process_status
</PRE>
<A NAME="@manual778"></A><BLOCKQUOTE>
<CODE>wait_pid p</CODE> suspends the execution of the calling thread
until the Unix process specified by the process identifier <CODE>p</CODE>
terminates. A pid <CODE>p</CODE> of <CODE>-1</CODE> means wait for any child.
A pid of <CODE>0</CODE> means wait for any child in the same process group
as the current process. Negative pid arguments represent
process groups. Returns the pid of the child caught and
its termination status, as per <CODE>Unix.wait</CODE>. 
</BLOCKQUOTE>
<PRE>
val wait_signal : int list -&gt; int
</PRE>
<A NAME="@manual779"></A><BLOCKQUOTE>
<CODE>wait_signal sigs</CODE> suspends the execution of the calling thread
until the process receives one of the signals specified in the
list <CODE>sigs</CODE>. It then returns the number of the signal received.
Signal handlers attached to the signals in <CODE>sigs</CODE> will not
be invoked. Do not call <CODE>wait_signal</CODE> concurrently 
from several threads on the same signals. 
</BLOCKQUOTE>


<H2>21.2&nbsp;&nbsp; Module <TT>Mutex</TT>: locks for mutual exclusion</H2><A NAME="s:Mutex"></A>
<A NAME="@manual780"></A><BLOCKQUOTE>
Mutexes (mutual-exclusion locks) are used to implement critical sections
and protect shared mutable data structures against concurrent accesses.
The typical use is (if <CODE>m</CODE> is the mutex associated with the data structure
<CODE>D</CODE>):

<PRE>
     Mutex.lock m;
     (* Critical section that operates over D *);
     Mutex.unlock m
</PRE>
</BLOCKQUOTE>
<PRE>
type t
</PRE>
<BLOCKQUOTE>
The type of mutexes. 
</BLOCKQUOTE>
<PRE>
val create: unit -&gt; t
</PRE>
<A NAME="@manual781"></A><BLOCKQUOTE>
Return a new mutex. 
</BLOCKQUOTE>
<PRE>
val lock: t -&gt; unit
</PRE>
<A NAME="@manual782"></A><BLOCKQUOTE>
Lock the given mutex. Only one thread can have the mutex locked
at any time. A thread that attempts to lock a mutex already locked
by another thread will suspend until the other thread unlocks
the mutex. 
</BLOCKQUOTE>
<PRE>
val try_lock: t -&gt; bool
</PRE>
<A NAME="@manual783"></A><BLOCKQUOTE>
Same as <CODE>try_lock</CODE>, but does not suspend the calling thread if
the mutex is already locked: just return <CODE>false</CODE> immediately
in that case. If the mutex is unlocked, lock it and
return <CODE>true</CODE>. 
</BLOCKQUOTE>
<PRE>
val unlock: t -&gt; unit
</PRE>
<A NAME="@manual784"></A><BLOCKQUOTE>
Unlock the given mutex. Other threads suspended trying to lock
the mutex will restart. 
</BLOCKQUOTE>


<H2>21.3&nbsp;&nbsp; Module <TT>Condition</TT>: condition variables to synchronize between threads</H2><A NAME="s:Condition"></A>
<A NAME="@manual785"></A><BLOCKQUOTE>
Condition variables are used when one thread wants to wait until another
thread has finished doing something: the former thread ``waits'' on the
condition variable, the latter thread ``signals'' the condition when it
is done. Condition variables should always be protected by a mutex.
The typical use is (if <CODE>D</CODE> is a shared data structure, <CODE>m</CODE> its mutex,
and <CODE>c</CODE> is a condition variable):

<PRE>
     Mutex.lock m;
     while (* some predicate P over D is not satisfied *) do
       Condition.wait c m
     done;
     (* Modify D *)
     if (* the predicate P over D is now satified *) then Condition.signal c;
     Mutex.unlock m
</PRE>
</BLOCKQUOTE>
<PRE>
type t
</PRE>
<BLOCKQUOTE>
The type of condition variables. 
</BLOCKQUOTE>
<PRE>
val create: unit -&gt; t
</PRE>
<A NAME="@manual786"></A><BLOCKQUOTE>
Return a new condition variable. 
</BLOCKQUOTE>
<PRE>
val wait: t -&gt; Mutex.t -&gt; unit
</PRE>
<A NAME="@manual787"></A><BLOCKQUOTE>
<CODE>wait c m</CODE> atomically unlocks the mutex <CODE>m</CODE> and suspends the
calling process on the condition variable <CODE>c</CODE>. The process will
restart after the condition variable <CODE>c</CODE> has been signalled.
The mutex <CODE>m</CODE> is locked again before <CODE>wait</CODE> returns. 
</BLOCKQUOTE>
<PRE>
val signal: t -&gt; unit
</PRE>
<A NAME="@manual788"></A><BLOCKQUOTE>
<CODE>signal c</CODE> restarts one of the processes waiting on the 
condition variable <CODE>c</CODE>. 
</BLOCKQUOTE>
<PRE>
val broadcast: t -&gt; unit
</PRE>
<A NAME="@manual789"></A><BLOCKQUOTE>
<CODE>broadcast c</CODE> restarts all processes waiting on the 
condition variable <CODE>c</CODE>. 
</BLOCKQUOTE>


<H2>21.4&nbsp;&nbsp; Module <TT>Event</TT>: first-class synchronous communication</H2><A NAME="s:Event"></A>
<A NAME="@manual790"></A><BLOCKQUOTE>
This module implements synchronous inter-thread communications over
channels. As in John Reppy's Concurrent ML system, the communication 
events are first-class values: they can be built and combined
independently before being offered for communication. 
</BLOCKQUOTE>
<PRE>
type 'a channel
</PRE>
<BLOCKQUOTE>
The type of communication channels carrying values of type <CODE>'a</CODE>. 
</BLOCKQUOTE>
<PRE>
val new_channel: unit -&gt; 'a channel
</PRE>
<A NAME="@manual791"></A><BLOCKQUOTE>
Return a new channel. 
</BLOCKQUOTE>
<PRE>
type 'a event
</PRE>
<BLOCKQUOTE>
The type of communication events returning a result of type <CODE>'a</CODE>. 
</BLOCKQUOTE>
<PRE>
val send: 'a channel -&gt; 'a -&gt; unit event
</PRE>
<A NAME="@manual792"></A><BLOCKQUOTE>
<CODE>send ch v</CODE> returns the event consisting in sending the value <CODE>v</CODE>
over the channel <CODE>ch</CODE>. The result value of this event is <CODE>()</CODE>. 
</BLOCKQUOTE>
<PRE>
val receive: 'a channel -&gt; 'a event
</PRE>
<A NAME="@manual793"></A><BLOCKQUOTE>
<CODE>receive ch</CODE> returns the event consisting in receiving a value
from the channel <CODE>ch</CODE>. The result value of this event is the
value received. 
</BLOCKQUOTE>
<PRE>
val always: 'a -&gt; 'a event
</PRE>
<A NAME="@manual794"></A><BLOCKQUOTE>
<CODE>always v</CODE> returns an event that is always ready for
synchronization. The result value of this event is <CODE>v</CODE>. 
</BLOCKQUOTE>
<PRE>
val choose: 'a event list -&gt; 'a event
</PRE>
<A NAME="@manual795"></A><BLOCKQUOTE>
<CODE>choose evl</CODE> returns the event that is the alternative of
all the events in the list <CODE>evl</CODE>. 
</BLOCKQUOTE>
<PRE>
val wrap: 'a event -&gt; ('a -&gt; 'b) -&gt; 'b event
</PRE>
<A NAME="@manual796"></A><BLOCKQUOTE>
<CODE>wrap ev fn</CODE> returns the event that performs the same communications
as <CODE>ev</CODE>, then applies the post-processing function <CODE>fn</CODE>
on the return value. 
</BLOCKQUOTE>
<PRE>
val wrap_abort: 'a event -&gt; (unit -&gt; unit) -&gt; 'a event
</PRE>
<A NAME="@manual797"></A><BLOCKQUOTE>
<CODE>wrap_abort ev fn</CODE> returns the event that performs
the same communications as <CODE>ev</CODE>, but if it is not selected
the function <CODE>fn</CODE> is called after the synchronization. 
</BLOCKQUOTE>
<PRE>
val guard: (unit -&gt; 'a event) -&gt; 'a event
</PRE>
<A NAME="@manual798"></A><BLOCKQUOTE>
<CODE>guard fn</CODE> returns the event that, when synchronized, computes
<CODE>fn()</CODE> and behaves as the resulting event. This allows to
compute events with side-effects at the time of the synchronization
operation. 
</BLOCKQUOTE>
<PRE>
val sync: 'a event -&gt; 'a
</PRE>
<A NAME="@manual799"></A><BLOCKQUOTE>
``Synchronize'' on an event: offer all the communication 
possibilities specified in the event to the outside world,
and block until one of the communications succeed. The result
value of that communication is returned. 
</BLOCKQUOTE>
<PRE>
val select: 'a event list -&gt; 'a
</PRE>
<A NAME="@manual800"></A><BLOCKQUOTE>
``Synchronize'' on an alternative of events.
<CODE>select evl</CODE> is shorthand for <CODE>sync(choose evl)</CODE>. 
</BLOCKQUOTE>
<PRE>
val poll: 'a event -&gt; 'a option
</PRE>
<A NAME="@manual801"></A><BLOCKQUOTE>
Non-blocking version of <CODE>sync</CODE>: offer all the communication 
possibilities specified in the event to the outside world,
and if one can take place immediately, perform it and return
<CODE>Some r</CODE> where <CODE>r</CODE> is the result value of that communication.
Otherwise, return <CODE>None</CODE> without blocking. 
</BLOCKQUOTE>


<H2>21.5&nbsp;&nbsp; Module <TT>ThreadUnix</TT>: thread-compatible system calls</H2><A NAME="s:ThreadUnix"></A>
<A NAME="@manual802"></A><BLOCKQUOTE>
This module reimplements some of the functions from <CODE>Unix</CODE>
so that they only block the calling thread, not all threads
in the program, if they cannot complete immediately.
See the documentation of the <CODE>Unix</CODE> module for more
precise descriptions of the functions below. 
</BLOCKQUOTE>

<H3>Process handling </H3>
<PRE>
val execv : string -&gt; string array -&gt; unit
val execve : string -&gt; string array -&gt; string array -&gt; unit
val execvp : string -&gt; string array -&gt; unit
val wait : unit -&gt; int * Unix.process_status
val waitpid : Unix.wait_flag list -&gt; int -&gt; int * Unix.process_status
val system : string -&gt; Unix.process_status
</PRE>
<A NAME="@manual803"></A><A NAME="@manual804"></A><A NAME="@manual805"></A><A NAME="@manual806"></A><A NAME="@manual807"></A><A NAME="@manual808"></A>
<H3>Basic input/output </H3>
<PRE>
val read : Unix.file_descr -&gt; string -&gt; int -&gt; int -&gt; int
val write : Unix.file_descr -&gt; string -&gt; int -&gt; int -&gt; int
</PRE>
<A NAME="@manual809"></A><A NAME="@manual810"></A>
<H3>Input/output with timeout </H3>
<PRE>
val timed_read : Unix.file_descr -&gt; string -&gt; int -&gt; int -&gt; float -&gt; int
val timed_write : Unix.file_descr -&gt; string -&gt; int -&gt; int -&gt; float -&gt; int
</PRE>
<A NAME="@manual811"></A><A NAME="@manual812"></A><BLOCKQUOTE>
Behave as <CODE>read</CODE> and <CODE>write</CODE>, except that 
<CODE>Unix_error(ETIMEDOUT,_,_)</CODE> is raised if no data is
available for reading or ready for writing after <CODE>d</CODE> seconds.
The delay <CODE>d</CODE> is given in the fifth argument, in seconds. 
</BLOCKQUOTE>

<H3>Polling </H3>
<PRE>
val select :
  Unix.file_descr list -&gt; Unix.file_descr list -&gt;
  Unix.file_descr list -&gt; float -&gt;
        Unix.file_descr list * Unix.file_descr list * Unix.file_descr list
</PRE>
<A NAME="@manual813"></A>
<H3>Pipes and redirections </H3>
<PRE>
val pipe : unit -&gt; Unix.file_descr * Unix.file_descr
val open_process_out: string -&gt; out_channel
val open_process: string -&gt; in_channel * out_channel
</PRE>
<A NAME="@manual814"></A><A NAME="@manual815"></A><A NAME="@manual816"></A>
<H3>Time </H3>
<PRE>
val sleep : int -&gt; unit
</PRE>
<A NAME="@manual817"></A>
<H3>Sockets </H3>
<PRE>
val socket : Unix.socket_domain -&gt; Unix.socket_type -&gt; int -&gt; Unix.file_descr
val socketpair : Unix.socket_domain -&gt; Unix.socket_type -&gt; int -&gt;
                 Unix.file_descr * Unix.file_descr
val accept : Unix.file_descr -&gt; Unix.file_descr * Unix.sockaddr
val connect : Unix.file_descr -&gt; Unix.sockaddr -&gt; unit
val recv : Unix.file_descr -&gt; string -&gt; int -&gt; int -&gt; Unix.msg_flag list -&gt; int
val recvfrom : Unix.file_descr -&gt; string -&gt; int -&gt; int -&gt;
               Unix.msg_flag list -&gt; int * Unix.sockaddr
val send : Unix.file_descr -&gt; string -&gt; int -&gt; int -&gt;
           Unix.msg_flag list -&gt; int
val sendto : Unix.file_descr -&gt; string -&gt; int -&gt; int -&gt;
             Unix.msg_flag list -&gt; Unix.sockaddr -&gt; int
val open_connection : Unix.sockaddr -&gt; in_channel * out_channel
val establish_server :
      (in_channel -&gt; out_channel -&gt; 'a) -&gt; Unix.sockaddr -&gt; unit
</PRE>
<A NAME="@manual818"></A><A NAME="@manual819"></A><A NAME="@manual820"></A><A NAME="@manual821"></A><A NAME="@manual822"></A><A NAME="@manual823"></A><A NAME="@manual824"></A><A NAME="@manual825"></A><A NAME="@manual826"></A><A NAME="@manual827"></A>


<HR>
<A HREF="manual062.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="manual064.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
</BODY>
</HTML>