shared-block-ring

A single-consumer single-producer queue on a block device
IN THIS PACKAGE
include S.RING with type disk := B.t with type item = Item.t
type t
type item = Item.t
type error = [
| `Retry
| `Suspended
| `Msg of string
]
type 'a result = ( 'a, error ) Result.result
val pp_error : Format.formatter -> error -> unit
val open_error : 'a result -> ( 'a, [> error ] ) Result.result
val error_to_msg : 'a result -> ( 'a, S.msg ) Result.result
val attach : ?queue:string -> ?client:string -> disk:B.t -> unit -> t result Lwt.t

attach queue client blockdevice attaches to a previously-created shared ring on top of blockdevice.

val detach : t -> unit Lwt.t

detach t frees all resources associated with t. Attempts to use t after a detach will result in an `Error _

val state : t -> [ `Running | `Suspended ] result Lwt.t

state t () queries the current state of the ring. If the result is `Suspended then the producer has acknowledged and will nolonger produce items. Clients which support suspend/resume should arrange to call this function periodically.

val debug_info : t -> (string * string) list result Lwt.t

debug_info t returns a list of key=value pairs which may be useful for debugging. Nothing should be assumed about the keys or the values; they should only be printed or logged.

type position

The position within a stream

val sexp_of_position : position -> Sexplib0.Sexp.t
include S.COMPARABLE with type t := position
val compare : position -> position -> [ `LessThan | `Equal | `GreaterThan ]

Compare two items

val advance : t:t -> position:position -> unit -> unit result Lwt.t

advance t position exposes the item associated with position to the Consumer so it can be popped.

val create : disk:B.t -> unit -> unit result Lwt.t

create blockdevice initialises a shared ring on top of blockdevice where we will be able to push variable-sized items.

val push : t:t -> item:item -> unit -> position result Lwt.t

push t item pushes item onto the ring t but doesn't expose it to the Consumer. `Ok position means the update has been safely written to the block device and can be exposed to the Consumer by calling advance position. `Error message indicates some fatal software bug: the message should be logged and the process shutdown. `Suspend means that the consumer has requested that no more items be pushed onto the queue temporarily `Retry means that the item should fit but there is temporarily not enough space in the ring. The client should retry later.