Module Lwt_pipe.Unbounded

Unbounded is a variant of Bounded where there is no size limit. It is equivalent to using Bounded with compute_size = Fun.const 0 but some functions are specialised to this particular setup.

type 'a t

Type of queues holding values of type 'a.

val create : unit -> 'a t

create () is an empty unbounded queue.

val push : 'a t -> 'a -> unit

push q v: v is added immediately to q.

Note that pushing never needs to wait for room to be available inside the pipe. As a result, push returns unit. This is unlike Bounded.push, where Bounded.push may need to wait for some space to be freed inside the pipe and thus returns unit Lwt.t.

  • raises {!Closed}

    if q is closed.

val pop : 'a t -> 'a Lwt.t

pop q is a promise that is pending until there is at least one element in q. When this happens an element is removed and the promise is fulfilled with it.

If there is already an element in q when the call is made, the element is removed immediately and an already resolved promise is returned.

  • raises {!Closed}

    if q is empty and closed. More specifically, the promise is rejected with Closed if q is empty and closed.

val pop_with_timeout : unit Lwt.t -> 'a t -> 'a option Lwt.t

pop_with_timeout t q is a promise that behaves similarly to pop q except that it resolves with None if t resolves before there is an element in q to pop.

Note that there can be multiple promises that are awaiting for an element to pop from the queue. As a result, it is possible that pop_with_timeout is fulfilled with None even though values have been pushed to the q.

t is canceled (i.e., it fails with Canceled) if an element is returned.

  • raises {!Closed}

    if q is empty and closed. More specifically, the promise is rejected with Closed if q is empty and closed.

val pop_all : 'a t -> 'a list Lwt.t

pop_all q is a promise that is pending until there is at least one element in q. When this happens, all the elements of q are removed and the promise is fulfilled with the list of elements (in the order in which they were inserted).

If there is already one or more elements in q when the call is made, the elements are removed immediately and an already resolved promise is returned.

  • raises {!Closed}

    if q is empty and closed. More specifically, the promise is rejected with Closed if q is empty and closed.

    In practice, this function returns a promise that either:

    • is pending and will resolve with a single-element list,
    • is already resolved with a list of at least one element,
    • or will be rejected with Closed.
val pop_all_now : 'a t -> 'a list

pop_all_now q removes and returns all the elements in q (in the order in which they were inserted). If q is empty, [] is returned.

  • raises {!Closed}

    if q is empty and closed.

val peek : 'a t -> 'a Lwt.t

peek q returns the same value as pop q but does not remove the returned element.

  • raises {!Closed}

    if q is empty and closed. More specifically, the promise is rejected with Closed if q is empty and closed.

val peek_all_now : 'a t -> 'a list

peek_all_now q returns the elements in the q (oldest first), or [] if empty. It does not remove elements from q.

  • raises {!Closed}

    if q is empty and closed.

val pop_now : 'a t -> 'a option

pop_now q may remove and return the first element in q if q contains at least one element.

  • raises Closed

    if q is closed.

val length : 'a t -> int

length q is the number of elements in q.

val is_empty : 'a t -> bool

is_empty q is true if q is empty, false otherwise.

val close : 'a t -> unit

close q the write-end of q:

  • Future write attempts will fail with Closed.
  • If there is data left in the pipe, then future read attempts will be resolved until the remaining data is drained, after which further reads will fail with Closed.
  • If there is no data left in the pipe, then pending and future reads will fail with Closed.

The close function is idempotent.

val is_closed : 'a t -> bool

is_closed q is true if close q has been called. It is false otherwise.