OCaml Library Collection
/

A flow can be used to read or write bytes.

Flows are used to represent byte streams, such as open files and network sockets. A source provides a stream of bytes. A sink consumes a stream. A two_way can do both.

To read structured data (e.g. a line at a time), wrap a source using Buf_read.

Types

type source_ty = [
  1. | `R
  2. | `Flow
]
type 'a source = ([> source_ty ] as 'a) Std.r

A readable flow provides a stream of bytes.

type sink_ty = [
  1. | `W
  2. | `Flow
]
type 'a sink = ([> sink_ty ] as 'a) Std.r

A writeable flow accepts a stream of bytes.

type shutdown_ty = [
  1. | `Shutdown
]
type 'a shutdown = ([> shutdown_ty ] as 'a) Std.r
type 'a read_method = ..

Sources can offer a list of ways to read them, in order of preference.

type shutdown_command = [
  1. | `Receive
    (*

    Indicate that no more reads will be done

    *)
  2. | `Send
    (*

    Indicate that no more writes will be done

    *)
  3. | `All
    (*

    Indicate that no more reads or writes will be done

    *)
]

Reading

val single_read : _ source -> Cstruct.t -> int

single_read src buf reads one or more bytes into buf.

It returns the number of bytes read (which may be less than the buffer size even if there is more data to be read).

  • Use read_exact instead if you want to fill buf completely.
  • Use Buf_read.line to read complete lines.
  • Use copy to stream data directly from a source to a sink.

buf must not be zero-length.

val read_exact : _ source -> Cstruct.t -> unit

read_exact src dst keeps reading into dst until it is full.

val string_source : string -> source_ty Std.r

string_source s is a source that gives the bytes of s.

val cstruct_source : Cstruct.t list -> source_ty Std.r

cstruct_source cs is a source that gives the bytes of cs.

type read_method +=
  1. | Read_source_buffer of 't -> (Cstruct.t list -> int) -> unit
    (*

    If a source offers Read_source_buffer rsb then the user can call rsb t fn to borrow a view of the source's buffers. fn returns the number of bytes it consumed.

    rsb will raise End_of_file if no more data will be produced. If no data is currently available, rsb will wait for some to become available before calling fn.

    fn must not continue to use the buffers after it returns.

    *)

Writing

val write : _ sink -> Cstruct.t list -> unit

write dst bufs writes all bytes from bufs.

You should not perform multiple concurrent writes on the same flow (the output may get interleaved).

This is a low level API. Consider using:

  • Buf_write to combine multiple small writes.
  • copy for bulk transfers, as it allows some extra optimizations.
val single_write : _ sink -> Cstruct.t list -> int

single_write dst bufs writes at least one byte from bufs and returns the number of bytes written.

val copy : _ source -> _ sink -> unit

copy src dst copies data from src to dst until end-of-file.

val copy_string : string -> _ sink -> unit

copy_string s = copy (string_source s)

val buffer_sink : Buffer.t -> sink_ty Std.r

buffer_sink b is a sink that adds anything sent to it to b.

To collect data as a cstruct, use Buf_read instead.

Bidirectional streams

type two_way_ty = [
  1. | source_ty
  2. | sink_ty
  3. | shutdown_ty
]
type 'a two_way = ([> two_way_ty ] as 'a) Std.r
val shutdown : _ two_way -> shutdown_command -> unit

shutdown t cmd indicates that the caller has finished reading or writing t (depending on cmd).

This is useful in some protocols to indicate that you have finished sending the request, and that the remote peer should now send the response.

Closing

Flows are usually attached to switches and closed automatically when the switch finishes. However, it can be useful to close them sooner manually in some cases.

val close : [> `Close ] Std.r -> unit

Alias of Resource.close.

Provider Interface

module Pi : sig ... end

Convenience wrappers

val read_all : _ source -> string

read_all src is a convenience wrapper to read an entire flow.

It is the same as Buf_read.(parse_exn take_all) src ~max_size:max_int