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
0). Other exceptions are ones caused by the
backend read/write functions, such as
Exception raised when a channel is closed. The parameter is a description of the channel.
Type of buffered byte channels
make ?buffer_size ?close ~mode perform_io is the
main function for creating new channels.
close ch closes the given channel. If
ch is an output
channel, it performs all pending actions, flushes it and closes
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
Note: you cannot use
close on channels obtained with
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.
read_line ic reads one complete line from
ic and returns it
without the end of line. End of line is either
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
For example if you use write_line in two different threads, the two operations will be serialized, and lines cannot be mixed.
The general name of a printing function is
<prefix> is one of:
'f', which means that the function takes as argument a channel
'e', which means that the function prints on stderr
<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 string
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
not specified, a fresh one will be used.
The connection is completly closed when you close both channels.
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
Common interface for reading/writing integers in binary
|: Lwt_bytes.t||;||(*||The internal buffer||*)|
# mutable da_ptr
|: int||;||(*||The pointer to:||*)|
# mutable da_max
|: int||;||(*||The maximum offset||*)|
|: 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
Return the default size for buffers. Channels that are created without a specific size use this one.
Change the default buffer size.
Invalid_argumentif the given size is smaller than
16or greater than