ocaml-multicore / domain-local-timeout

A scheduler independent timeout mechanism

API reference

domain-local-timeout — Scheduler independent timeout

A low level mechanism intended for writing higher level libraries that need to be able to have scheduler friendly timeouts.

A library that needs timeouts may simply call set_timeoutf.

To provide an efficient scheduler specific implementation of the mechanism, schedulers may install an implementation by wrapping the scheduler main loop with a call to using. The implementation is then stored in a domain, and optionally thread, local variable. The overhead that this imposes on a scheduler should be insignificant.

An application can then choose to use schedulers that provide the necessary implementation or, for example, use the default implementation by calling set_system.

The end result is effective interoperability between schedulers and concurrent programming libraries.

References

DLT is used by the following libraries:

• Kcas uses DLT to implement timeouts.

Example

First we require some libraries we are using:

# #thread
# #require "domain-local-timeout"
# #require "domain-local-await"

Here is how one could implement a scheduler independent and friendly way to sleep:

# let sleepf seconds =
    let t = Domain_local_await.prepare_for_await () in
    let cancel = Domain_local_timeout.set_timeoutf seconds t.release in
    try t.await ()
    with exn ->
      cancel ();
      raise exn
val sleepf : float -> unit = <fun>

Note that the above is careful to call cancel in case await raises an exception. That could happen when the fiber on which sleepf was called is canceled, in which case it makes sense to cancel the timeout.

Let's try it:

# sleepf 1.0
Exception: Failure "Domain_local_timeout.set_timeoutf not implemented".

Oops!

To actually use domain-local-timeout we need an implementation. There is a default implementation that uses the Stdlib.Thread and Stdlib.Unix modules, but it is also possible to implement the facility in other ways and it is recommended for schedulers to provide their own optimized implementations. Both of those system modules are optional and are not provided on all platforms. For these reasons domain-local-timeout does not directly depend on those libraries. To use the default implementation, we need to require those libraries and tell domain-local-timeout that it can use those system libraries:

# Domain_local_timeout.set_system (module Thread) (module Unix)
- : unit = ()

Now we are ready to try setting timeouts:

# let cancel =
    Domain_local_timeout.set_timeoutf 0.1 @@ fun () ->
    Printf.printf "world!\n%!"
  in
  Printf.printf "Hello, %!";
  try sleepf 0.2
  with exn ->
    cancel ();
    raise exn
Hello, world!
- : unit = ()

The above example first registers a timeout to print the end of the message and then immediately prints the beginning. Finally the example sleeps a bit to wait for the end to be printed.