Module net::tcp

Variants

• generic_connect_err(str, str) - Some unplanned-for error. The first and second fields correspond to libuv's err_name and err_msg fields, respectively.
• connection_refused - Invalid IP or invalid port

Method read_start

fn read_start() ->
   result::result<comm::port<result::result<~[u8], tcp_err_data>>,
                  tcp_err_data>

Method read_stop

fn read_stop(-read_port: comm::port<result::result<~[u8], tcp_err_data>>) ->
   result::result<(), tcp_err_data>

Method read

fn read(timeout_msecs: uint) -> result::result<~[u8], tcp_err_data>

Method read_future

fn read_future(timeout_msecs: uint) ->
   future::future<result::result<~[u8], tcp_err_data>>

Method write

fn write(raw_write_data: ~[u8]) -> result::result<(), tcp_err_data>

Method write_future

fn write_future(raw_write_data: ~[u8]) ->
   future::future<result::result<(), tcp_err_data>>

Method read_bytes

fn read_bytes(amt: uint) -> ~[u8]

Method read_byte

fn read_byte() -> int

Method unread_byte

fn unread_byte(amt: int)

Method eof

fn eof() -> bool

Method seek

fn seek(dist: int, seek: io::seek_style)

Method tell

fn tell() -> uint

Method write

fn write(data: & [const u8])

Method seek

fn seek(dist: int, seek: io::seek_style)

Method tell

fn tell() -> uint

Method flush

fn flush() -> int

Notes

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.

Example

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 = comm::port::<option<tcp_err_data>>();
    let cont_ch = comm::chan(cont_po);
    task::spawn {||
        let accept_result = net::tcp::accept(new_conn);
        if accept_result.is_err() {
            comm::send(cont_ch, result::get_err(accept_result));
            // fail?
        }
        else {
            let sock = result::get(accept_result);
            comm::send(cont_ch, true);
            // do work here
        }
    };
    alt comm::recv(cont_po) {
      // shut down listen()
      some(err_data) { comm::send(kill_chan, some(err_data)) }
      // wait for next connection
      none {}
    }
};

Arguments

• new_conn - an opaque value used to create a new tcp_socket

Returns

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.

Arguments

• input_ip - The IP address (versions 4 or 6) of the remote host
• port - the unsigned integer of the desired remote host port
• iotask - a uv::iotask that the tcp request will run on

Returns

A 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

Arguments

• host_ip - a net::ip::ip_addr representing a unique IP (versions 4 or 6)
• port - a uint representing the port to listen on
• backlog - a uint representing the number of incoming connections to cache in memory
• hl_loop - a uv::hl::high_level_loop that the tcp request will run on
• on_establish_cb - a callback that is evaluated if/when the listener is successfully established. it takes no parameters
• new_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 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.

returns

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

Arguments

• sock -- a net::tcp::tcp_socket for the connection to read from

Returns

• A result instance that will either contain a 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 record

Arguments

• sock - a net::tcp::tcp_socket that you wish to stop reading on

Arguments

• sock -- a net::tcp::tcp_socket that you want to buffer

Returns

A buffered wrapper that you can cast as an io::reader or io::writer

Arguments

• sock - a tcp_socket to write to
• raw_write_data - a vector of [u8]/~ that will be written to the stream. This value must remain valid for the duration of the write call

Returns

A result object with a nil value as the ok variant, or a tcp_err_data value as the err variant

Safety

This function can produce unsafe results if:

1. the call to write_future is made
2. the future::future value returned is never resolved via future::get
3. and then the 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.

Arguments

• sock - a tcp_socket to write to
• raw_write_data - a vector of [u8]/~ that will be written to the stream. This value must remain valid for the duration of the write call

Returns

A 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