Programs that use the threads library must be linked as follows:

        nmlc -thread other options threads.cma other files

The -thread option selects a special, thread-safe version of the standard library (see chapter 8). The -thread option must also be given when compiling any source file that references modules from the thread library (Thread, Mutex, ...).

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:

        nmlc -thread other options threads.cma other files

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.

Programs that use the threads library must be linked as follows:

        nmlc -thread other options threads.cma other files

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 8).

type t

The type of thread handles.

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.

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 -> timeout:float -> bool
val wait_timed_write : Unix.file_descr -> timeout: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 :
  read:Unix.file_descr list -> write:Unix.file_descr list ->
  exn:Unix.file_descr list -> timeout: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.

val wait_signal : int list -> int

wait_signal sigs suspends the execution of the calling thread until the process receives one of the signals specified in the list sigs. It then returns the number of the signal received. Signal handlers attached to the signals in sigs will not be invoked. Do not call wait_signal concurrently from several threads on the same signals.

val yield : unit -> unit

Re-schedule the calling thread without suspending it. This function can be used to give scheduling hints, telling the scheduler that now is a good time to switch to other threads.

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.

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 -> locking: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.

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.

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 -> f:('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 wrap_abort: 'a event -> f:(unit -> unit) -> 'a event

wrap_abort ev fn returns the event that performs the same communications as ev, but if it is not selected the function fn is called after the synchronization.

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.

This module is deprecated: its functionality has been merged back into the Unix module. Threaded programs can now call the functions from module Unix directly, and still get the correct behavior (block the calling thread, if required, but do not block all threads in the process).

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

val read : Unix.file_descr -> buf:string -> pos:int -> len:int -> int
val write : Unix.file_descr -> buf:string -> pos:int -> len:int -> int

val timed_read :
      Unix.file_descr ->
      buf:string -> pos:int -> len:int -> timeout:float -> int
val timed_write :
      Unix.file_descr ->
      buf:string -> pos:int -> len:int -> timeout: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.

val select :
  read:Unix.file_descr list -> write:Unix.file_descr list ->
  except:Unix.file_descr list -> timeout:float ->
        Unix.file_descr list * Unix.file_descr list * Unix.file_descr list

val pipe : unit -> Unix.file_descr * Unix.file_descr
val open_process_in: string -> in_channel
val open_process_out: string -> out_channel
val open_process: string -> in_channel * out_channel
val open_process_full:
      string -> env:string array -> in_channel * out_channel * in_channel

val sleep : int -> unit

val socket : domain:Unix.socket_domain ->
             kind:Unix.socket_type -> protocol:int -> Unix.file_descr
val socketpair : domain:Unix.socket_domain -> kind:Unix.socket_type ->
                 protocol:int -> Unix.file_descr * Unix.file_descr
val accept : Unix.file_descr -> Unix.file_descr * Unix.sockaddr
val connect : Unix.file_descr -> addr:Unix.sockaddr -> unit
val recv : Unix.file_descr -> buf:string ->
           pos:int -> len:int -> mode:Unix.msg_flag list -> int
val recvfrom : Unix.file_descr -> buf:string -> pos:int -> len:int ->
               mode:Unix.msg_flag list -> int * Unix.sockaddr
val send : Unix.file_descr -> buf:string -> pos:int -> len:int ->
           mode:Unix.msg_flag list -> int
val sendto : Unix.file_descr -> buf:string -> pos:int -> len:int ->
             mode:Unix.msg_flag list -> addr:Unix.sockaddr -> int
val open_connection : Unix.sockaddr -> in_channel * out_channel
val establish_server :
      (in_channel -> out_channel -> unit) ->
      addr:Unix.sockaddr -> unit