Previous Next Contents

The threads library

The threads 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.

The threads 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.

Unix:
Programs that use the threads library must be linked as follows: 
        ocamlc -thread -custom other options threads.cma other files -cclib -lthreads
All object files on the command line must also have been compiled with the -thread option, which selects a special, thread-safe version of the standard library (see chapter 7).

The default thread implementation cannot be used in native-code programs compiled with ocamlopt. If your operating system provides POSIX 1003.1c compliant threads, you can select an alternate implementation when configuring Objective Caml (use the -with-pthread option to configure) which also supports native-code programs. Programs that use this alternate implementation of the threads library must be linked as follows: 

        ocamlc -thread -custom other options threads.cma other files \
                 -cclib -lthreads -cclib -lunix -cclib -lpthread
        ocamlopt -thread other options threads.cmxa other files \
                -cclib -lthreadsnat -cclib -lunix -cclib -lpthread
Depending on the operating system, extra system libraries can be necessary. For instance, under Solaris 2.5, add -cclib -lposix4 at the end of the command line.

Windows:
Programs that use the threads library must be linked as follows: 
        ocamlc -thread -custom other options threads.cma other files \
                %CAMLLIB%/libthreads.lib %CAMLLIB%/libunix.lib
        ocamlopt -thread -custom other options threads.cmxa other files \
                %CAMLLIB%/libthreadsnat.lib %CAMLLIB%/libunix.lib
All object files on the command line must also have been compiled with the -thread option, which selects a special, thread-safe version of the standard library (see chapter 7).

Module Thread: lightweight threads

type t
The type of thread handles.

Thread creation and termination 

val create : ('a -> 'b) -> 'a -> t
Thread.create funct arg creates a new thread of control, in which the function application funct arg is executed concurrently with the other threads of the program. The application of Thread.create returns the handle of the newly created thread. The new thread terminates when the application funct arg 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 funct arg is discarded and not directly accessible to the parent thread. 
val self : unit -> t
Return the thread currently executing. 
val id : t -> int
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. 
val exit : unit -> unit
Terminate prematurely the currently executing thread. 
val kill : t -> unit
Terminate prematurely the thread whose handle is given. This functionality is available only with bytecode-level threads.

Suspending threads 

val delay: float -> unit
delay d suspends the execution of the calling thread for d seconds. The other program threads continue to run during this time. 
val join : t -> unit
join th suspends the execution of the calling thread until the thread th has terminated. 
val wait_read : Unix.file_descr -> unit
val wait_write : Unix.file_descr -> unit
Suspend the execution of the calling thread until at least one character is available for reading (wait_read) or one character can be written without blocking (wait_write) on the given Unix file descriptor. 
val wait_timed_read : Unix.file_descr -> float -> bool
val wait_timed_write : Unix.file_descr -> float -> bool
Same as wait_read and wait_write, but wait for at most the amount of time given as second argument (in seconds). Return true if the file descriptor is ready for input/output and false if the timeout expired. 
val select :
  Unix.file_descr list -> Unix.file_descr list ->
  Unix.file_descr list -> float ->
    Unix.file_descr list * Unix.file_descr list * Unix.file_descr list
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 Unix.select. 
val wait_pid : int -> int * Unix.process_status
wait_pid p suspends the execution of the calling thread until the Unix process specified by the process identifier p terminates. A pid p of -1 means wait for any child. A pid of 0 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 Unix.wait.

Module Mutex: locks for mutual exclusion

Mutexes (mutual-exclusion locks) are used to implement critical sections and protect shared mutable data structures against concurrent accesses. The typical use is (if m is the mutex associated with the data structure D): 
     Mutex.lock m;
     (* Critical section that operates over D *);
     Mutex.unlock m


type t
The type of mutexes. 
val create: unit -> t
Return a new mutex. 
val lock: t -> unit
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. 
val try_lock: t -> bool
Same as try_lock, but does not suspend the calling thread if the mutex is already locked: just return false immediately in that case. If the mutex is unlocked, lock it and return true. 
val unlock: t -> unit
Unlock the given mutex. Other threads suspended trying to lock the mutex will restart.

Module Condition: condition variables to synchronize between threads

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 D is a shared data structure, m its mutex, and c is a condition variable): 
     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


type t
The type of condition variables. 
val create: unit -> t
Return a new condition variable. 
val wait: t -> Mutex.t -> unit
wait c m atomically unlocks the mutex m and suspends the calling process on the condition variable c. The process will restart after the condition variable c has been signalled. The mutex m is locked again before wait returns. 
val signal: t -> unit
signal c restarts one of the processes waiting on the condition variable c. 
val broadcast: t -> unit
broadcast c restarts all processes waiting on the condition variable c.

Module Event: first-class synchronous communication

This module implements synchronous interprocess 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. 
type 'a channel
The type of communication channels carrying values of type 'a. 
val new_channel: unit -> 'a channel
Return a new channel. 
type 'a event
The type of communication events returning a result of type 'a. 
val send: 'a channel -> 'a -> unit event
send ch v returns the event consisting in sending the value v over the channel ch. The result value of this event is (). 
val receive: 'a channel -> 'a event
receive ch returns the event consisting in receiving a value from the channel ch. The result value of this event is the value received. 
val always: 'a -> 'a event
always v returns an event that is always ready for synchronization. The result value of this event is v. 
val choose: 'a event list -> 'a event
choose evl returns the event that is the alternative of all the events in the list evl. 
val wrap: 'a event -> ('a -> 'b) -> 'b event
wrap ev fn returns the event that performs the same communications as ev, then applies the post-processing function fn on the return value. 
val guard: (unit -> 'a event) -> 'a event
guard fn returns the event that, when synchronized, computes fn() and behaves as the resulting event. This allows to compute events with side-effects at the time of the synchronization operation. 
val sync: 'a event -> 'a
``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. 
val select: 'a event list -> 'a
``Synchronize'' on an alternative of events. select evl is shorthand for sync(choose evl). 
val poll: 'a event -> 'a option
Non-blocking version of sync: offer all the communication possibilities specified in the event to the outside world, and if one can take place immediately, perform it and return Some r where r is the result value of that communication. Otherwise, return None without blocking.

Module ThreadUnix: thread-compatible system calls

This module reimplements some of the functions from Unix so that they only block the calling thread, not all threads in the program, if they cannot complete immediately. See the documentation of the Unix module for more precise descriptions of the functions below.

Process handling 

val execv : string -> string array -> unit
val execve : string -> string array -> string array -> unit
val execvp : string -> string array -> unit
val wait : unit -> int * Unix.process_status
val waitpid : Unix.wait_flag list -> int -> int * Unix.process_status
val system : string -> Unix.process_status

Basic input/output 

val read : Unix.file_descr -> string -> int -> int -> int
val write : Unix.file_descr -> string -> int -> int -> int

Input/output with timeout 

val timed_read : Unix.file_descr -> string -> int -> int -> float -> int
val timed_write : Unix.file_descr -> string -> int -> int -> float -> int
Behave as read and write, except that Unix_error(ETIMEDOUT,_,_) is raised if no data is available for reading or ready for writing after d seconds. The delay d is given in the fifth argument, in seconds.

Polling 

val select :
  Unix.file_descr list -> Unix.file_descr list ->
  Unix.file_descr list -> float ->
        Unix.file_descr list * Unix.file_descr list * Unix.file_descr list

Pipes and redirections 

val pipe : unit -> Unix.file_descr * Unix.file_descr
val open_process_out: string -> out_channel
val open_process: string -> in_channel * out_channel

Time 

val sleep : int -> unit

Sockets 

val socket : Unix.socket_domain -> Unix.socket_type -> int -> Unix.file_descr
val socketpair : Unix.socket_domain -> Unix.socket_type -> int ->
                 Unix.file_descr * Unix.file_descr
val accept : Unix.file_descr -> Unix.file_descr * Unix.sockaddr
val connect : Unix.file_descr -> Unix.sockaddr -> unit
val recv : Unix.file_descr -> string -> int -> int -> Unix.msg_flag list -> int
val recvfrom : Unix.file_descr -> string -> int -> int ->
               Unix.msg_flag list -> int * Unix.sockaddr
val send : Unix.file_descr -> string -> int -> int ->
           Unix.msg_flag list -> int
val sendto : Unix.file_descr -> string -> int -> int ->
             Unix.msg_flag list -> Unix.sockaddr -> int
val open_connection : Unix.sockaddr -> in_channel * out_channel
val establish_server :
      (in_channel -> out_channel -> 'a) -> Unix.sockaddr -> unit
Previous Next Contents