Thread library is deprecated


I read from Chapter 30 of the manual, The threads library,

Warning: the threads library is deprecated since version 4.08.0 of OCaml. Please switch to system threads, which have the same API.

Can someone explain what it means exactly?

  • “switch to system threads”. I thought system threads were part of the Thread library
  • “same API”. Same as what?

Sorry if this sounds obvious


Historically, OCaml has been providing two ways to write threaded program:

  • via plain system threads, which is what most people have been using
  • via an alternative implementation of Pervasives, Unix, Threads, Condition, … where all threads where running on the same system thread and IOs where multiplexed using a select loop. This is similar to what libraries such as Lwt or Async do, except without the monad

The second way was known under the name “vmthreads”. It wasn’t very well known anymore and wasn’t used very much. Additionally, it was a lot of work to maintain. Indeed, it required to maintain a parallel implementation of many modules. So we decided to deprecate it.

In practice, the majority of users can ignore this. In particular, people who didn’t know about vmthreads can safely ignore this. The Thread library using system thread is still present and maintained.


I think it’s still worth opening an issue or PR a documentation clarification. It’s not the threads library that is deprecated it’s the vmthread implementation that is.


thanks for the clarification!
I agree with @dbuenzli that the sentence in the manual could be clarified. I first thought I had to completely reorganize my program…

Follow-up to this: where is it? :slight_smile: I mean, the currently-maintained Thread library. Is it in the Thread module? Because that module says that it’s a ‘lightweight’ thread. I’m not sure where the system thread module is.

Both threads implementation shared the same interface that is exposed as the Thread module. So yes, this module is what you use to access system threads (or, in the past, vm/green-threads).

I wish one of the participants to the thread above had submitted a PR or at least opened an upstream issue to clarify the documentation. This is a silly/unfortunate confusion, and it is easy to fix. (I had missed the present topic so far.)

It looks like Daniel came close to it in this issue but missed the Thread module documentation itself:

I’ve now created a new issue:

While we are in the topic of threads, does mirage support ocaml Threads(system thread) module/lib?

I don’t believe so. Mirage is single threaded but offers concurrency via lwt.

1 Like

Ah. okay. Thanks for the confirmation.