High-level interface to libuv's TCP functionality
ConnectReqData
TcpBufferedSocketData
TcpErrData
- Contains raw, string-based, error information returned from libuvTcpListenFcData
TcpSocketCloseData
TcpSocketData
WriteReqData
ConnAttempt
TcpConnectErrData
- Details returned as part of a result::err
result from tcp::connect
TcpConnectResult
TcpListenErrData
- Details returned as part of a result::err
result from tcp::listen
TcpNewConnection
TcpReadResult
TcpReadStartResult
TcpWriteResult
TcpSocket
- Encapsulates an open TCP/IP connection through libuvTcpSocketBuf
- A buffered wrapper for net::tcp::tcp_socket
ToTcpErr
of Drop for TcpSocket
for TcpSocket
- Convenience methods extending net::tcp::tcp_socket
of io::Reader for TcpSocketBuf
- Implementation of io::reader
trait for a buffered net::tcp::tcp_socket
of io::Writer for TcpSocketBuf
- Implementation of io::reader
trait for a buffered net::tcp::tcp_socket
of ToTcpErr for uv::ll::uv_err_data
TcpSocket
TcpSocketBuf
accept
- Bind an incoming client connection to a net::tcp::tcp_socket
connect
- Initiate a client connection over TCP/IPlisten
- Bind to a given IP/port and listen for new connectionslisten_common
malloc_uv_tcp_t
on_alloc_cb
on_tcp_read_cb
read
- Reads a single chunk of data from tcp_socket
; block until data/error recv'dread_common_impl
read_future
- Reads a single chunk of data; returns a future::future<~[u8]>
immediatelyread_start
- Begin reading binary data from an open TCP connection; used with read_stop
read_start_common_impl
read_stop
- Stop reading from an open TCP connection; used with read_start
read_stop_common_impl
socket_buf
- Convert a net::tcp::tcp_socket
to a net::tcp::tcp_socket_buf
.stream_error_close_cb
tcp_connect_close_cb
tcp_connect_on_connect_cb
tcp_lfc_close_cb
tcp_lfc_on_connection_cb
tcp_socket_dtor_close_cb
tcp_write_complete_cb
tear_down_socket_data
write
- Write binary data to a tcp stream; Blocks until operation completeswrite_common_impl
write_future
- Write binary data to tcp stream; Returns a future::future
value immediatelynet_tcp::test
net_tcp::rustrt
ConnectReqData
type ConnectReqData = {result_ch: oldcomm::Chan<ConnAttempt>, closed_signal_ch: oldcomm::Chan<()>,}
TcpBufferedSocketData
type TcpBufferedSocketData = {sock: TcpSocket, mut buf: ~[u8],}
TcpErrData
type TcpErrData = {err_name: ~str, err_msg: ~str,}
Contains raw, string-based, error information returned from libuv
TcpListenFcData
type TcpListenFcData = {server_stream_ptr: *uv::ll::uv_tcp_t,
stream_closed_ch: oldcomm::Chan<()>,
kill_ch: oldcomm::Chan<Option<TcpErrData>>,
on_connect_cb: ~fn(*uv::ll::uv_tcp_t),
iotask: IoTask,
ipv6: bool,
mut active: bool,}
TcpSocketCloseData
type TcpSocketCloseData = {closed_ch: oldcomm::Chan<()>,}
TcpSocketData
type TcpSocketData = {reader_po: oldcomm::Port<result::Result<~[u8], TcpErrData>>,
reader_ch: oldcomm::Chan<result::Result<~[u8], TcpErrData>>,
stream_handle_ptr: *uv::ll::uv_tcp_t,
connect_req: uv::ll::uv_connect_t,
write_req: uv::ll::uv_write_t,
ipv6: bool,
iotask: IoTask,}
WriteReqData
type WriteReqData = {result_ch: oldcomm::Chan<TcpWriteResult>,}
ConnAttempt
ConnSuccess
ConnFailure(uv::ll::uv_err_data)
TcpConnectErrData
Details returned as part of a result::err
result from tcp::connect
GenericConnectErr(~str, ~str)
- Some unplanned-for error. The first and second fields correspond to libuv's err_name
and err_msg
fields, respectively.ConnectionRefused
- Invalid IP or invalid portTcpConnectResult
TcpConnected(TcpSocket)
TcpConnectError(TcpErrData)
TcpListenErrData
Details returned as part of a result::err
result from tcp::listen
GenericListenErr(~str, ~str)
- Some unplanned-for error. The first and second fields correspond to libuv's err_name
and err_msg
fields, respectively.AddressInUse
- Failed to bind to the requested IP/Port, because it is already in use.AccessDenied
- Request to bind to an IP/Port was denied by the system.TcpNewConnection
NewTcpConn(*uv::ll::uv_tcp_t)
TcpReadResult
TcpReadData(~[u8])
TcpReadDone
TcpReadErr(TcpErrData)
TcpReadStartResult
TcpReadStartSuccess(oldcomm::Port<TcpReadResult>)
TcpReadStartError(TcpErrData)
TcpWriteResult
TcpWriteSuccess
TcpWriteError(TcpErrData)
TcpSocket
pub struct TcpSocket {
socket_data: @TcpSocketData,
}
Encapsulates an open TCP/IP connection through libuv
tcp_socket
is non-copyable/sendable and automagically handles closing the underlying libuv data structures when it goes out of scope. This is the data structure that is used for read/write operations over a TCP stream.
TcpSocketBuf
pub struct TcpSocketBuf {
data: @TcpBufferedSocketData,
mut end_of_stream: bool,
}
A buffered wrapper for net::tcp::tcp_socket
It is created with a call to net::tcp::socket_buf()
and has impls that satisfy both the io::reader
and io::writer
traits.
ToTcpErr
to_tcp_err
fn to_tcp_err() -> TcpErrData
Drop
for TcpSocket
finalize
fn finalize()
TcpSocket
Convenience methods extending net::tcp::tcp_socket
read_start
fn read_start() ->
result::Result<oldcomm::Port<result::Result<~[u8], TcpErrData>>, TcpErrData>
read_stop
fn read_stop(read_port: oldcomm::Port<result::Result<~[u8], TcpErrData>>) ->
result::Result<(), TcpErrData>
read
fn read(timeout_msecs: uint) -> result::Result<~[u8], TcpErrData>
read_future
fn read_future(timeout_msecs: uint) ->
future::Future<result::Result<~[u8], TcpErrData>>
write
fn write(raw_write_data: ~[u8]) -> result::Result<(), TcpErrData>
write_future
fn write_future(raw_write_data: ~[u8]) ->
future::Future<result::Result<(), TcpErrData>>
get_peer_addr
fn get_peer_addr() -> ip::IpAddr
io::Reader
for TcpSocketBuf
Implementation of io::reader
trait for a buffered net::tcp::tcp_socket
read
fn read(buf: &[mut u8], len: uint) -> uint
read_byte
fn read_byte() -> int
eof
fn eof() -> bool
seek
fn seek(dist: int, seek: io::SeekStyle)
tell
fn tell() -> uint
io::Writer
for TcpSocketBuf
Implementation of io::reader
trait for a buffered net::tcp::tcp_socket
write
fn write(data: &[const u8])
seek
fn seek(dist: int, seek: io::SeekStyle)
tell
fn tell() -> uint
flush
fn flush() -> int
get_type
fn get_type() -> io::WriterType
ToTcpErr
for uv::ll::uv_err_data
to_tcp_err
fn to_tcp_err() -> TcpErrData
TcpSocket
fn TcpSocket(socket_data: @TcpSocketData) -> TcpSocket
TcpSocketBuf
fn TcpSocketBuf(data: @TcpBufferedSocketData) -> TcpSocketBuf
accept
fn accept(new_conn: TcpNewConnection) -> result::Result<TcpSocket, TcpErrData>
Bind an incoming client connection to a net::tcp::tcp_socket
It is safe to call net::tcp::accept
only within the context of the new_connect_cb
callback provided as the final argument to the net::tcp::listen
function.
The new_conn
opaque value is provided only as the first argument to the new_connect_cb
provided as a part of net::tcp::listen
. It can be safely sent to another task but it must be used (via net::tcp::accept
) before the new_connect_cb
call it was provided to returns.
This implies that a port/chan pair must be used to make sure that the new_connect_cb
call blocks until an attempt to create a net::tcp::tcp_socket
is completed.
Here, the new_conn
is used in conjunction with accept
from within a task spawned by the new_connect_cb
passed into listen
net::tcp::listen(remote_ip, remote_port, backlog)
// this callback is ran once after the connection is successfully
// set up
{|kill_ch|
// pass the kill_ch to your main loop or wherever you want
// to be able to externally kill the server from
}
// this callback is ran when a new connection arrives
{|new_conn, kill_ch|
let cont_po = core::comm::port::<option<tcp_err_data>>();
let cont_ch = core::comm::chan(cont_po);
task::spawn {||
let accept_result = net::tcp::accept(new_conn);
if accept_result.is_err() {
core::comm::send(cont_ch, result::get_err(accept_result));
// fail?
}
else {
let sock = result::get(accept_result);
core::comm::send(cont_ch, true);
// do work here
}
};
match core::comm::recv(cont_po) {
// shut down listen()
some(err_data) { core::comm::send(kill_chan, some(err_data)) }
// wait for next connection
none {}
}
};
new_conn
- an opaque value used to create a new tcp_socket
On success, this function will return a net::tcp::tcp_socket
as the ok
variant of a result
. The net::tcp::tcp_socket
is anchored within the task that accept
was called within for its lifetime. On failure, this function will return a net::tcp::tcp_err_data
record as the err
variant of a result
.
connect
fn connect(input_ip: ip::IpAddr, port: uint, iotask: IoTask) ->
result::Result<TcpSocket, TcpConnectErrData>
Initiate a client connection over TCP/IP
input_ip
- The IP address (versions 4 or 6) of the remote hostport
- the unsigned integer of the desired remote host portiotask
- a uv::iotask
that the tcp request will run onA result
that, if the operation succeeds, contains a net::net::tcp_socket
that can be used to send and receive data to/from the remote host. In the event of failure, a net::tcp::tcp_connect_err_data
instance will be returned
listen
fn listen(host_ip: ip::IpAddr, port: uint, backlog: uint, iotask: IoTask,
on_establish_cb: ~fn(oldcomm::Chan<Option<TcpErrData>>),
new_connect_cb:
~fn(TcpNewConnection, oldcomm::Chan<Option<TcpErrData>>)) ->
result::Result<(), TcpListenErrData>
Bind to a given IP/port and listen for new connections
host_ip
- a net::ip::ip_addr
representing a unique IP (versions 4 or 6)port
- a uint representing the port to listen onbacklog
- a uint representing the number of incoming connections to cache in memoryhl_loop
- a uv::hl::high_level_loop
that the tcp request will run onon_establish_cb
- a callback that is evaluated if/when the listener is successfully established. it takes no parametersnew_connect_cb
- a callback to be evaluated, on the libuv thread, whenever a client attempts to conect on the provided ip/port. the callback's arguments are:
new_conn
- an opaque type that can be passed to net::tcp::accept
in order to be converted to a tcp_socket
.kill_ch
- channel of type core::comm::chan<option<tcp_err_data>>
. this channel can be used to send a message to cause listen
to begin closing the underlying libuv data structures.a result
instance containing empty data of type ()
on a successful/normal shutdown, and a tcp_listen_err_data
enum in the event of listen exiting because of an error
listen_common
fn listen_common(host_ip: ip::IpAddr, port: uint, backlog: uint,
iotask: IoTask,
on_establish_cb: ~fn(oldcomm::Chan<Option<TcpErrData>>),
on_connect_cb: ~fn(*uv::ll::uv_tcp_t)) ->
result::Result<(), TcpListenErrData>
malloc_uv_tcp_t
fn malloc_uv_tcp_t() -> *uv::ll::uv_tcp_t
on_alloc_cb
fn on_alloc_cb(handle: *libc::c_void, suggested_size: size_t) ->
uv::ll::uv_buf_t
on_tcp_read_cb
fn on_tcp_read_cb(stream: *uv::ll::uv_stream_t, nread: libc::ssize_t,
++buf: uv::ll::uv_buf_t)
read
fn read(sock: &TcpSocket, timeout_msecs: uint) ->
result::Result<~[u8], TcpErrData>
Reads a single chunk of data from tcp_socket
; block until data/error recv'd
Does a blocking read operation for a single chunk of data from a tcp_socket
until a data arrives or an error is received. The provided timeout_msecs
value is used to raise an error if the timeout period passes without any data received.
sock
- a net::tcp::tcp_socket
that you wish to read fromtimeout_msecs
- a uint
value, in msecs, to wait before dropping the read attempt. Pass 0u
to wait indefinitelyread_common_impl
fn read_common_impl(socket_data: *TcpSocketData, timeout_msecs: uint) ->
result::Result<~[u8], TcpErrData>
read_future
fn read_future(sock: &TcpSocket, timeout_msecs: uint) ->
future::Future<result::Result<~[u8], TcpErrData>>
Reads a single chunk of data; returns a future::future<~[u8]>
immediately
Does a non-blocking read operation for a single chunk of data from a tcp_socket
and immediately returns a future
value representing the result. When resolving the returned future
, it will block until data arrives or an error is received. The provided timeout_msecs
value is used to raise an error if the timeout period passes without any data received.
This function can produce unsafe results if the call to read_future
is made, the future::future
value returned is never resolved via future::get
, and then the tcp_socket
passed in to read_future
leaves scope and is destructed before the task that runs the libuv read operation completes.
As such: If using read_future
, always be sure to resolve the returned future
so as to ensure libuv doesn't try to access a released read handle. Otherwise, use the blocking tcp::read
function instead.
sock
- a net::tcp::tcp_socket
that you wish to read fromtimeout_msecs
- a uint
value, in msecs, to wait before dropping the read attempt. Pass 0u
to wait indefinitelyread_start
fn read_start(sock: &TcpSocket) ->
result::Result<oldcomm::Port<result::Result<~[u8], TcpErrData>>, TcpErrData>
Begin reading binary data from an open TCP connection; used with read_stop
net::tcp::tcp_socket
for the connection to read fromresult
instance that will either contain a core::comm::port<tcp_read_result>
that the user can read (and optionally, loop on) from until read_stop
is called, or a tcp_err_data
recordread_start_common_impl
fn read_start_common_impl(socket_data: *TcpSocketData) ->
result::Result<oldcomm::Port<result::Result<~[u8], TcpErrData>>, TcpErrData>
read_stop
fn read_stop(sock: &TcpSocket,
read_port: oldcomm::Port<result::Result<~[u8], TcpErrData>>) ->
result::Result<(), TcpErrData>
Stop reading from an open TCP connection; used with read_start
sock
- a net::tcp::tcp_socket
that you wish to stop reading onread_stop_common_impl
fn read_stop_common_impl(socket_data: *TcpSocketData) ->
result::Result<(), TcpErrData>
socket_buf
fn socket_buf(sock: TcpSocket) -> TcpSocketBuf
Convert a net::tcp::tcp_socket
to a net::tcp::tcp_socket_buf
.
This function takes ownership of a net::tcp::tcp_socket
, returning it stored within a buffered wrapper, which can be converted to a io::reader
or io::writer
sock
-- a net::tcp::tcp_socket
that you want to bufferA buffered wrapper that you can cast as an io::reader
or io::writer
stream_error_close_cb
fn stream_error_close_cb(handle: *uv::ll::uv_tcp_t)
tcp_connect_close_cb
fn tcp_connect_close_cb(handle: *uv::ll::uv_tcp_t)
tcp_connect_on_connect_cb
fn tcp_connect_on_connect_cb(connect_req_ptr: *uv::ll::uv_connect_t,
status: libc::c_int)
tcp_lfc_close_cb
fn tcp_lfc_close_cb(handle: *uv::ll::uv_tcp_t)
tcp_lfc_on_connection_cb
fn tcp_lfc_on_connection_cb(handle: *uv::ll::uv_tcp_t, status: libc::c_int)
tcp_socket_dtor_close_cb
fn tcp_socket_dtor_close_cb(handle: *uv::ll::uv_tcp_t)
tcp_write_complete_cb
fn tcp_write_complete_cb(write_req: *uv::ll::uv_write_t, status: libc::c_int)
tear_down_socket_data
fn tear_down_socket_data(socket_data: @TcpSocketData)
write
fn write(sock: &TcpSocket, raw_write_data: ~[u8]) ->
result::Result<(), TcpErrData>
Write binary data to a tcp stream; Blocks until operation completes
tcp_socket
to write to~[u8]
that will be written to the stream. This value must remain valid for the duration of the write
callA result
object with a nil
value as the ok
variant, or a tcp_err_data
value as the err
variant
write_common_impl
fn write_common_impl(socket_data_ptr: *TcpSocketData, raw_write_data: ~[u8])
-> result::Result<(), TcpErrData>
write_future
fn write_future(sock: &TcpSocket, raw_write_data: ~[u8]) ->
future::Future<result::Result<(), TcpErrData>>
Write binary data to tcp stream; Returns a future::future
value immediately
This function can produce unsafe results if:
write_future
is madefuture::future
value returned is never resolved via future::get
tcp_socket
passed in to write_future
leaves scope and is destructed before the task that runs the libuv write operation completes.As such: If using write_future
, always be sure to resolve the returned future
so as to ensure libuv doesn't try to access a released write handle. Otherwise, use the blocking tcp::write
function instead.
tcp_socket
to write to~[u8]
that will be written to the stream. This value must remain valid for the duration of the write
callA future
value that, once the write
operation completes, resolves to a result
object with a nil
value as the ok
variant, or a tcp_err_data
value as the err
variant