Reader is Async's main API for buffered input from a file descriptor. It is the
Each reader has an internal buffer, which is filled via
read() system calls when
data is needed to satisfy a
Each of the read functions returns a deferred that will become determined when the read completes. It is an error to have two simultaneous reads. That is, if one calls a read function, one should not call another read function until the first one completes.
If the file descriptor underlying a reader is closed, the reader will return EOF (after all the buffered bytes have been read).
Reader.read* call could, rather than determine its result, send an exception to
the monitor in effect when
read was called. Such exceptions can be handled in the
usual way by using
try_with (fun () -> Reader.read reader ...)
io_stats Overall IO statistics for all readers
transfer t pipe_w transfers data from
pipe_w one chunk at a time
(whatever is read from the underlying file descriptor without post-processing). The
result becomes determined after reaching EOF on
t and the final bytes have been
transferred, or if
pipe_w is closed.
This function will normally not be needed (see
pipe t returns the reader end of a pipe that will continually be filled with chunks
of data from the underlying Reader.t. When the reader reaches EOF or the pipe is
pipe closes the the reader, and then after the reader close is finished,
closes the pipe.
of_pipe info pipe_r returns a reader
t that receives all the data from
pipe_r is closed,
t will see an EOF (but will not be automatically closed). If
t is closed, then
pipe_r will stop being drained.
of_pipe is implemented by shuttling bytes from
pipe_r to the write-end of a Unix
t being attached to the read end of the Unix pipe.
with_file file f opens
files, creates a reader with it, and passes the reader to
f. It closes the reader when the result of
f becomes determined, and returns
NOTE, you need to be careful that all your IO is done when the deferred you return
becomes determined. If for example, you use
with_file, and call
lines, make sure
you return a deferred that becomes determined when the EOF is reached on the pipe,
not when you get the pipe (because you get it straight away).
close t prevents further use of
t and closes
t's underlying file descriptor.
The result of
close becomes determined once the underlying file descriptor has been
closed. It is an error to call other operations on
close t has been
called, except that calls of
close subsequent to the original call to
return the same deferred as the original call.
close_finished t becomes determined after
t's underlying file descriptor has been
closed, i.e. it is the same as the result of
close_finished differs from
close in that it does not have the side effect of initiating a close.
is_closed t returns
close t has been called.
with_close t ~f runs
f (), and closes
f finishes or raises.
read_one_chunk_at_a_time t ~handle_chunk reads into
t's internal buffer,
and whenever bytes are available, applies
handle_chunk to them. It waits to read
again until the deferred returned by
handle_chunk becomes determined.
read_one_chunk_at_a_time continues reading until it reaches
`Stop_consumed. In the case of
one may read from
`Stop a or
`Continue respects the usual
Iobuf semantics where data up to the
Iobuf.Lo_bound is considered consumed.
read_one_iobuf_at_a_time is like
read_one_chunk_at_a_time, except that the
handle_chunk function receives its data in an
Iobuf.t, and uses the
Iobuf position to communicate how much data was consumed.
read_one_iobuf_at_a_time is implemented as a wrapper around
really_read t buf ?pos ?len reads until it fills
len bytes of
pos or runs out of input. In the former case it returns `Ok.
In the latter, it returns
`Eof n where
n is the number of bytes that
were read before end of input, and
0 <= n < String.length ss.
read_until t pred ~keep_delim reads until it hits a delimiter
c such that:
pred = `Char c'then
c = c'
pred = `Pred pthen
`Char c' is equivalent to
`Pred (fun c -> c = c') but the underlying
implementation is more efficient, in particular it will not call a function on every
read_until returns a freshly-allocated string consisting of all the characters read
and optionally including the delimiter as per
read_until, except you have the option of specifiying a maximum number of
chars to read.
read_line t reads up to, and including the next newline (\n) character (or \r\n) and
returns a freshly-allocated string containing everything up to but not including the
newline character. If
read_line encounters EOF before the newline char then
everything read up to but not including EOF will be returned as a line.
really_read_line ~wait_time t reads up to, and including the next newline (\n)
character and returns an optional, freshly-allocated string containing everything up
to but not including the newline character. If
really_read_line encounters EOF
before the newline char, then a time span of
wait_time will be used before the input
operation is retried. If the descriptor is closed,
None will be returned.
read_bin_prot ?max_len t bp_reader reads the next binary protocol message using
binary protocol reader
bp_reader. The format is the "size-prefixed binary
protocol", in which the length of the data is prefixed as a 64-bit integer to the
data. This is the format that
For higher performance, consider
Read and return a buffer containing one marshaled value, but don't unmarshal it. You can just call Marshal.from_string on the string, and cast it to the desired type (preferrably the actual type). similar to Marshal.from_channel, but suffers from the String-length limitation (16MB) on 32bit platforms.
read_all t read_one returns a pipe that receives all values read from
read_one t. When the reader reaches EOF, it closes the reader,
and then after the reader close is finished, closes the pipe.
lseek t offset ~mode clears
t's buffer and calls
`Cur mode is not exposed because seeking relative to the current
position of the file descriptor is not the same as seeking to relative to the current
position of the reader.
lines t reads all the lines from
t and puts them in the pipe, one line per pipe
element. The lines do not contain the trailing newline. When the reader reaches EOF
or the pipe is closed,
lines closes the the reader, and then after the reader close
is finished, closes the pipe.
file_contents file returns the string with the full contents of the file
file_lines file returns a list of the lines in the file. The lines do not contain
the trailing newline.
load_sexp file conv loads a sexp from
file and converts it to a value using
conv. This function provides an accurate error location if
load_sexps is similar, but converts a sequence of sexps.
~expand_macros:true expands macros as defined in Sexplib.Macro. If
~expand_macros:true then the
exclusive flag is ignored. Also,
~expand_macros:true, and will raise.