Module Luv__.Stream
type 'kind t
= [ `Stream of 'kind ] Luv.Handle.t
Binds
uv_stream_t
.
val shutdown : _ t -> ((unit, Luv.Error.t) Result.result -> unit) -> unit
Shuts down the write side of the stream.
Binds
uv_shutdown
. Seeshutdown(3p)
.
val listen : ?backlog:int -> _ t -> ((unit, Luv.Error.t) Result.result -> unit) -> unit
Starts listening for incoming connections.
Binds
uv_listen
. Seelisten(3p)
.The default value of
?backlog
isSOMAXCONN
.
val accept : server:'kind t -> client:'kind t -> (unit, Luv.Error.t) Result.result
Accepts an incoming connection.
Binds
uv_accept
. Seeaccept(3p)
.~client
should be a freshly-initialized stream of the same kind as~server
. In other words, if~server
is aLuv.TCP.t
,~client
should also be aLuv.TCP.t
, and should have been obtained fromLuv.TCP.init
.
val read_start : ?allocate:(int -> Luv.Buffer.t) -> _ t -> ((Luv.Buffer.t, Luv.Error.t) Result.result -> unit) -> unit
Calls its callback whenever data is available on the stream.
Binds
uv_read_start
. Seeread(3p)
.The amount of data read is equal to the length of the buffer passed to the callback.
?allocate
is called immediately before each call to the main callback withOk buffer'
, to createbuffer
, into which the data will be read.buffer'
is, in general, a view intobuffer
. The default?allocate
allocates a fresh buffer every time it is called. One particular use of?allocate
is to always read data into the same pre-existing buffer. Theint
argument passed to?allocate
is a suggested size. It is acceptable to return a buffer of a smaller size. To read into an existing buffer, but not at its beginning, useLuv.Buffer.sub
to create a view into the buffer.The end of the stream (typically, when the remote peer closes or shuts down the connection) is indicated by
Error `EOF
being passed to the callback. Note that this behavior is different fromLuv.File.read
.Zero-length reads are possible, and do not indicate the end of stream. Instead, they usually indicate
EAGAIN
inside libuv; libuv still calls the callback in order to give the C user a chance to deallocate the data buffer. This is not usually an issue in OCaml, so a wrapper of this function can usually simply ignore zero-length reads. It is then also safe to convertError `EOF
to zero-length reads in a higher-level API, for consistency with reading files, and in accordance with OS API convention.To read only once, call
Luv.Stream.read_stop
immediately, in the main callback. Otherwise, the main callback will be called repeatedly.
val read_stop : _ t -> (unit, Luv.Error.t) Result.result
Stops reading.
Binds
uv_read_stop
.
val write : _ t -> Luv.Buffer.t list -> ((unit, Luv.Error.t) Result.result -> int -> unit) -> unit
Writes the given buffer to the stream.
Binds
uv_write
. Seewritev(3p)
.To write only part of a buffer, use
Luv.Buffer.sub
to create a view into the buffer, and pass the view to this functionLuv.Stream.write
.The second argument passed to the callback is the number of bytes written. libuv has an internal queue of writes, in part to implement retry. This means that writes can be partial at the libuv (and Luv) API level, so it is possible to receive both an
Error
result, and for some data to have been successfully written.
val write2 : [< `Pipe ] t -> Luv.Buffer.t list -> send_handle:[< `TCP | `Pipe ] t -> ((unit, Luv.Error.t) Result.result -> int -> unit) -> unit
Like
Luv.Stream.write
, but allows sending a TCP socket or pipe over the stream (~send_handle
). The stream must be a pipe.Binds
uv_write2
.
val try_write : _ t -> Luv.Buffer.t list -> (int, Luv.Error.t) Result.result
Like
Luv.Stream.write
, but only attempts to perform the write operation immediately.Binds
uv_try_write
.
val is_readable : _ t -> bool
Indicates whether the given stream is readable (has data).
Binds
uv_is_readable
.
val is_writable : _ t -> bool
Indicates whether the given stream is writable (has space in buffers).
Binds
uv_is_writable
.
val set_blocking : _ t -> bool -> (unit, Luv.Error.t) Result.result
Sets the blocking mode of a stream.
Binds
uv_stream_set_blocking
.