Buffered byte channels
A channel is a high-level object for performing input/output (IO). It allows to read/write from/to the outside world in an efficient way, by minimising the number of system calls.
An output channel is used to send data and an input channel is used to receive data.
If you are familiar with buffered channels you may be familiar too with the flush operation. Note that byte channels of this module are automatically flushed when there is nothing else to do (i.e. before the program becomes idle), so this means that you no longer have to write:
eprintf "log message\n";
flush stderr;
to have your messages displayed.
Note about errors: input functions of this module raise
End_of_file
when the end-of-file is reached (i.e. when the read
function returns 0
). Other exceptions are ones caused by the
backend read/write functions, such as Unix.Unix_error
.
Exception raised when a channel is closed. The parameter is a description of the channel.
Type of buffered byte channels
Input mode
Output mode
make ?buffer_size ?close ~mode perform_io
is the
main function for creating new channels.
Sys.max_string_length
Lwt.return
Unix.lseek
close ch
closes the given channel. If ch
is an output
channel, it performs all pending actions, flushes it and closes
it. If ch
is an input channel, it just closes it immediately.
close
returns the result of the close function of the
channel. Multiple calls to close
will return exactly the same
value.
Note: you cannot use close
on channels obtained with
atomic.
is_busy channel
returns whether the given channel is currently
busy. A channel is busy when there is at least one job using it
that has not yet terminated.
Note: except for functions dealing with streams (read_chars and read_lines) all functions are atomic.
read_char ic
reads the next character of ic
.
End_of_file
if the end of the file is reached
Same as [root:read_byte] but does not raise End_of_file
on end of
input
read_chars ic
returns a stream holding all characters of
ic
read_line ic
reads one complete line from ic
and returns it
without the end of line. End of line is either "\n"
or
"\r\n"
.
If the end of line is reached before reading any character,
End_of_file
is raised. If it is reached before reading an end
of line but characters have already been read, they are
returned.
Same as read_line but do not raise End_of_file
on end of
input.
read_lines ic
returns a stream holding all lines of ic
read ?count ic
reads at most len
characters from ic
. It
returns ""
if the end of input is reached. If count
is not
specified, it reads all bytes until the end of input.
read_into ic buffer offset length
reads up to length
bytes,
stores them in buffer
at offset offset
, and returns the
number of bytes read.
Note: read_into
does not raise End_of_file
, it returns a
length of 0
instead.
read_into_exactly ic buffer offset length
reads exactly
length
bytes and stores them in buffer
at offset offset
.
End_of_file
on end of input
Note: as for reading functions, all functions except write_chars and write_lines are atomic.
For example if you use write_line in two different threads, the two operations will be serialized, and lines cannot be mixed.
write_chars oc chars
writes all characters of chars
on
oc
write_line oc str
writes str
on oc
followed by a
new-line.
write_lines oc lines
writes all lines of lines
to oc
write_from oc buffer offset length
writes up to length
bytes
to oc
, from buffer
at offset offset
and returns the number
of bytes actually written
write_from_exactly oc buffer offset length
writes all length
bytes from buffer
at offset offset
to oc
write_value oc ?flags x
marshals the value x
to oc
These functions are basically helpers. Also you may prefer using the name printl rather than write_line because it is shorter.
The general name of a printing function is <prefix>print<suffixes>
,
where <prefix>
is one of:
'f'
, which means that the function takes as argument a channel'e'
, which means that the function prints on stderrand <suffixes>
is a combination of:
'l'
which means that a new-line character is printed after the message'f'
which means that the function takes as argument a format instead
of a stringhexdump_stream oc byte_stream
produces the same output as the
command hexdump -C
.
hexdump oc str = hexdump_stream oc (Lwt_stream.of_string str)
Type of file names
with_file ?buffer_size ?flags ?perm ~mode filename f
opens a
file and passes the channel to f
. It is ensured that the
channel is closed when f ch
terminates (even if it fails).
open_connection ?fd ?buffer_size addr
opens a connection to the
given address and returns two channels for using it. If fd
is
not specified, a fresh one will be used.
The connection is completly closed when you close both channels.
Unix.Unix_error
on error.
with_connection ?fd ?buffer_size addr f
opens a connection to
the given address and passes the channels to f
Type of a server
establish_server ?fd ?buffer_size ?backlog sockaddr f
creates a
server which will listen for incoming connections. New connections
are passed to f
. Note that f
must not raise any exception. If
fd
is not specified, a fresh file descriptor will be created.
backlog
is the argument passed to Lwt_unix.listen
lines_of_file name
returns a stream of all lines of the file
with name name
. The file is automatically closed when all
lines have been read.
lines_to_file name lines
writes all lines of lines
to
file with name name
.
chars_of_file name
returns a stream of all characters of the
file with name name
. As for lines_of_file the file is
closed when all characters have been read.
chars_to_file name chars
writes all characters of chars
to
name
Common interface for reading/writing integers in binary
Writes an IEEE single precision floating point value
Writes an IEEE double precision floating point value
#
da_buffer
| : Lwt_bytes.t | ; | (* | The internal buffer | *) |
#
mutable da_ptr
| : int | ; | (* | The pointer to:
| *) |
#
mutable da_max
| : int | ; | (* | The maximum offset | *) |
#
da_perform
| : unit -> int Lwt.t | ; | (* | - for input channels:
refills the buffer and returns how many bytes have been read
| *) |
Information for directly accessing the internal buffer of a channel
direct_access ch f
passes to f
a direct_access
structure. f
must use it and update da_ptr
to reflect how
many bytes have been read/written.
Return the default size for buffers. Channels that are created without a specific size use this one.
Change the default buffer size.
Invalid_argument
if the given size is smaller than 16
or greater than Sys.max_string_length