Chapter 23 | 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 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:

>             ocamlc -thread other options threads.cma other files
>             ocamlopt -thread other options threads.cmxa 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.

Windows:

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

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

23.1 | 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 -> 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.

23.2 | 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.

23.3 | 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 -> 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`.

23.4 | Module `Event`: first-class synchronous communication

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

23.5 | Module `ThreadUnix`: thread-compatible system calls

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

Process handling

    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

Basic input/output

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

Input/output with timeout

    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.

Polling

    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

Pipes and redirections

    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

Time

    val sleep : int -> unit

Sockets

    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