package mirage-block-combinators

  1. Overview
  2. Docs

Safe block devices

Construct a safe wrapper around B where necessary buffer preconditions are checked on read and write, and useful error messages generated. Some concrete implementations generate confusing errors (e.g. Unix might say "EINVAL") which are harder to debug.

Parameters

module B : Mirage_block.S

Signature

type error = private [>
  1. | Mirage_block.error
  2. | `Unsafe of string
]

The type for errors.

type write_error = private [>
  1. | Mirage_block.write_error
  2. | `Unsafe of string
]

The type for write errors.

include Mirage_block.S with type t = B.t and type error := error and type write_error := write_error
val pp_error : error Fmt.t

pp_error is the pretty-printer for errors.

val pp_write_error : write_error Fmt.t

pp_write_error is the pretty-printer for write errors.

type t = B.t

The type representing the internal state of the block device

val disconnect : t -> unit Lwt.t

Disconnect from the device. While this might take some time to complete, it can never result in an error.

val get_info : t -> Mirage_block.info Lwt.t

Query the characteristics of a specific block device

val read : t -> int64 -> Cstruct.t list -> (unit, error) Stdlib.result Lwt.t

read device sector_start buffers reads data starting at sector_start from the block device into buffers. Ok () means the buffers have been filled. Error _ indicates an I/O error has happened and some of the buffers may not be filled. Each of elements in the list buffers must be a whole number of sectors in length. The list of buffers can be of any length. Some implementations may further require that each element in buffers is exactly sector_size long.

val write : t -> int64 -> Cstruct.t list -> (unit, write_error) Stdlib.result Lwt.t

write device sector_start buffers writes data from buffers onto the block device starting at sector_start. Ok () means the contents of the buffers have been written. Error _ indicates a partial failure in which some of the writes may not have happened.

Once submitted, it is not possible to cancel a request and there is no timeout.

The operation may fail with: `Is_read_only: the device is read-only, no data has been written.

Each of buffers must be a whole number of sectors in length. The list of buffers can be of any length. Some implementations may further require that each element in buffers is exactly sector_size long.

The data will not be copied, so the supplied buffers must not be re-used until the IO operation completes.

val unsafe_read : t -> int64 -> Cstruct.t list -> (unit, B.error) Stdlib.result Lwt.t

unsafe_read is like read except it bypasses the necessary buffer precondition checks. Only use this if you want maximum performance and if you can prove the preconditions are respected.

val unsafe_write : t -> int64 -> Cstruct.t list -> (unit, B.write_error) Stdlib.result Lwt.t

unsafe_write is like write except it bypasses the necessary buffer precondition checks. Only use this if you want maximum performance and if you can prove the buffer preconditions are respected.