Up

Module Thread_safe_queue

A thread-safe non-blocking queue of unbounded size.

The implementation does not use mutexes, and so is safe to use in situations when one doesn't want to block, e.g. a finalizer or an async job.

Signature

type 'a t
val sexp_of_t : ('a -> Sexplib.Sexp.t) -> 'a t -> Sexplib.Sexp.t
include Invariant.S1 with type 'a t := 'a t
type 'a t
val invariant : 'a Invariant_intf.inv -> 'a t Invariant_intf.inv
val create : unit -> 'a t

create () returns an empty queue.

val length : _ t -> int
val enqueue : 'a t -> 'a -> unit
val dequeue_exn : 'a t -> 'a

dequeue_exn t raises if length t = 0. The idiom for dequeueing a single element is:


      if length t > 0 then dequeue_exn t else ...

The idiom for dequeueing until empty is:


      while length t > 0 do
        let a = dequeue_exn t in
        ...
      done

These idioms work in the presence of threads because OCaml will not context switch between the length t > 0 test and the call to dequeue_exn. Also, if one has only a single thread calling dequeue_exn, then the idiom is obviously OK even in the presence of a context switch.

val clear_internal_pool : _ t -> unit

The queue maintains an internal pool of unused elements, which are used by enqueue and returned to the pool by dequeue_exn. enqueue creates a new element if the pool is empty. Nothing shrinks the pool automatically. One can call clear_internal_pool to clear the pool, so that all unused elements will be reclaimed by the garbage collector.