Module Eio.FlowSource

Byte streams.

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.

Reading

Sourcetype read_method = ..

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

Sourceclass virtual source : object ... end
Sourceval 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). single_read src just makes a single call to src#read_into (and asserts that the result is in range).

  • 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.

Sourceval read_exact : source -> Cstruct.t -> unit

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

Sourceval read_methods : source -> read_method list

read_methods flow is a list of extra ways of reading from flow, with the preferred (most efficient) methods first.

If no method is suitable, read should be used as the fallback.

Sourceval string_source : string -> source

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

Sourceval cstruct_source : Cstruct.t list -> source

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

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

    If a source offers Read_source_buffer rsb then the user can call rsb 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

Sourceclass virtual sink : object ... end

Consumer base class.

Sourceval 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.
Sourceval copy : source -> sink -> unit

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

Sourceval copy_string : string -> sink -> unit

copy_string s = copy (string_source s)

Sourceval buffer_sink : Buffer.t -> sink

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

Sourcetype 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

    *)
]
Sourceclass virtual two_way : object ... end
Sourceval 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.

Sourceclass type close = Eio__.Generic.close
Sourceval close : close -> unit

Alias of Generic.close.