mirage-channel 4.1.0 · OCaml Package

Functor to create a CHANNEL from a flow implementation

Parameters

module F : Mirage_flow.S

Signature

type error = private [>

| `Read_zero
| `Flow of F.error
| `Line_too_long

]

The type for errors.

val pp_error : error Fmt.t

pp_error is the pretty-printer for errors.

type write_error = private [>

| Mirage_flow.write_error

]

The type for write errors.

val pp_write_error : write_error Fmt.t

pp_write_error is the pretty-printer for write errors.

type flow = F.flow

The type for unbuffered network flow.

type t

The type for the state associated with channels, such as the inflight buffers.

val create : flow -> t

create flow allocates send and receive buffers and associates them with the given unbuffered flow.

val to_flow : t -> flow

to_flow t returns the flow that backs this channel.

val read_char : t -> (char Mirage_flow.or_eof, error) Stdlib.result Lwt.t

Reads a single character from the channel, blocking if there is no immediately available input data.

val read_some : 
  ?len:int ->
  t ->
  (Cstruct.t Mirage_flow.or_eof, error) Stdlib.result Lwt.t

read_some ?len t reads up to len characters from the input channel and at most a full buffer. If len is not specified, it reads all available data and returns that buffer.

val read_exactly : 
  len:int ->
  t ->
  (Cstruct.t list Mirage_flow.or_eof, error) Stdlib.result Lwt.t

read_exactly len t reads len bytes from the channel t or fails with Eof.

val read_line : 
  ?len:int ->
  t ->
  (Cstruct.t list Mirage_flow.or_eof, error) Stdlib.result Lwt.t

read_line t reads a line of input, which is terminated either by a CRLF sequence, or the end of the channel (which counts as a line).

If ?len is provided then the maximum length of the line returned will be len bytes. If the line is longer than len then an error will be returned. With len = 0, read_line always returns an error.

If the input data is untrusted then care should be taken to ensure len is set to an application-specific small value to bound the amount of memory allocated by read_line.

returns
Returns a list of views that terminates at EOF.

val write_char : t -> char -> unit

write_char t ch writes a single character to the output channel.

val write_string : t -> string -> int -> int -> unit

write_string t buf off len writes len bytes from a string buf, starting from from offset off.

val write_buffer : t -> Cstruct.t -> unit

write_buffer t buf copies the buffer to the channel's output buffer. The buffer should not be modified after being written, and it will be recycled into the buffer allocation pool at some future point.

val write_line : t -> string -> unit

write_line t buf writes the string buf to the output channel and append a newline character afterwards.

val flush : t -> (unit, write_error) Stdlib.result Lwt.t

flush t flushes the output buffer and block if necessary until it is all written out to the flow.

val close : t -> (unit, write_error) Stdlib.result Lwt.t

close t calls flush and then close the underlying flow.

package mirage-channel

Parameters

Signature