Module Picos_std_awaitable

Modules

Examples

We first open the library to bring the Awaitable module into scope:

  # open Picos_std_awaitable

Mutex

Here is a basic mutex implementation using awaitables:

  module Mutex = struct
    type t = int Awaitable.t

    let create ?padded () = Awaitable.make ?padded 0

    let lock t =
      if not (Awaitable.compare_and_set t 0 1) then
        while Awaitable.exchange t 2 <> 0 do
          Awaitable.await t 2
        done

    let unlock t =
      let before = Awaitable.fetch_and_add t (-1) in
      if before = 2 then begin
        Awaitable.set t 0;
        Awaitable.signal t
      end
  end

The above mutex outperforms most other mutexes under both no/low and high contention scenarios. In no/low contention scenarios the use of fetch_and_add provides low overhead. In high contention scenarios the above mutex allows unfairness, which avoids performance degradation due to the lock convoy phenomena.

Condition

Let's also implement a condition variable. For that we'll also make use of low level abstractions and operations from the Picos core library:

  # open Picos

To implement a condition variable, we'll use the Awaiter API:

  module Condition = struct
    type t = unit Awaitable.t

    let create () = Awaitable.make ()

    let wait t mutex =
      let trigger = Trigger.create () in
      let awaiter = Awaitable.Awaiter.add t trigger in
      Mutex.unlock mutex;
      let lock_forbidden mutex =
        let fiber = Fiber.current () in
        let forbid = Fiber.exchange fiber ~forbid:true in
        Mutex.lock mutex;
        Fiber.set fiber ~forbid
      in
      match Trigger.await trigger with
      | None -> lock_forbidden mutex
      | Some exn_bt ->
          Awaitable.Awaiter.remove awaiter;
          lock_forbidden mutex;
          Printexc.raise_with_backtrace (fst exn_bt) (snd exn_bt)

    let signal = Awaitable.signal
    let broadcast = Awaitable.broadcast
  end

Notice that the awaitable location used in the above condition variable implementation is never mutated. We just reuse the signaling mechanism of awaitables.