package nbd

  1. Overview
  2. Docs

Parameters

Signature

include V1_LWT.BLOCK
type page_aligned_buffer = Cstruct.t

The type for page-aligned memory buffers.

type error = [
  1. | `Unknown of string
    (*

    an undiagnosed error

    *)
  2. | `Unimplemented
    (*

    operation not yet implemented in the code

    *)
  3. | `Is_read_only
    (*

    you cannot write to a read/only instance

    *)
  4. | `Disconnected
    (*

    the device has been previously disconnected

    *)
]

The type for IO operation errors.

include V1.DEVICE with type error := error with type 'a io = 'a Lwt.t
type 'a io = 'a Lwt.t

The type for potentially blocking I/O operation

type t

The type representing the internal state of the device

type id

This type is no longer used and will be removed once other * modules stop using it in their type signatures.

val disconnect : t -> unit io

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

type info = {
  1. read_write : bool;
    (*

    True if we can write, false if read/only

    *)
  2. sector_size : int;
    (*

    Octets per sector

    *)
  3. size_sectors : int64;
    (*

    Total sectors per device

    *)
}

Characteristics of the block device. Note some devices may be able to make themselves bigger over time.

val get_info : t -> info io

Query the characteristics of a specific block device

val read : t -> int64 -> page_aligned_buffer list -> [ `Error of error | `Ok of unit ] io

read device sector_start buffers returns a blocking IO operation which attempts to fill buffers with data starting at sector_start. Each of buffers must be a whole number of sectors in length. The list of buffers can be of any length.

val write : t -> int64 -> page_aligned_buffer list -> [ `Error of error | `Ok of unit ] io

write device sector_start buffers returns a blocking IO operation which attempts to write the data contained within buffers to t starting at sector_start. When the IO operation completes then all writes have been persisted.

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

The operation may fail with:

  • `Unimplemented: the operation has not been implemented, no data has been written.
  • `Is_read_only: the device is read-only, no data has been written.
  • `Disconnected: the device has been disconnected at application request, an unknown amount of data has been written.
  • `Unknown: some other permanent, fatal error (e.g. disk is on fire), where an unknown amount of 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.

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

val connect : ?progress_cb:([ `Percent of int | `Complete ] -> unit) -> Primary.t -> Secondary.t -> [ `Ok of t | `Error of error ] Lwt.t

connect ?progress primary secondary creates a block device which performs I/O against primary, while building a mirror of primary on top of secondary in the background. Existing data in secondary will be destroyed.

If ?progress_cb is provided then it will be called on every percentage change in mirror progress.

It is an error if the block size of either primary or secondary is not an integer multiple of the other.

It is an error if primary and secondary have different lengths.

It is an error if secondary is read-only.

val string_of_error : error -> string