NAME

UniEvent::Tcp - stream that represents both TCP streams and servers.

SYNOPSIS

    use UniEvent;

    my $tcp = UniEvent::Tcp->new;
    
    $tcp->connect($host, $port, sub {
        my ($tcp, $error) = @_;
        die("cannot connect: $error\n") if $error;
        ...
    });

    $tcp->write($data, sub {
        my ($tcp, $error) = @_;
        die("writing data error: $error\n") if $error;
        ...
    });

    $tcp->read_callback(sub {
        my ($tcp, $data, $error) = @_;
        die("reading data error: $error\n") if $error;
        ...
    });

    $tcp->eof_callback(sub {
        my $tcp = shift;
        ...
    });

    $tcp->loop->run;

DESCRIPTION

Tcp handle allows to establish TCP-connection to local or remote machine. It is able to work over IPv4 as well as over IPv6 protocols (aka dual stack mode), the difference between them is abstracted from user.

The Tcp hanlde is inherited from UniEvent::Stream where the most part of its functionality is documented.

METHODS

All methods of UniEvent::Stream also apply.

new([$loop = default], [$domain = AF_UNSPEC])

Constructs new Tcp handle and binds it to the specified event loop. The domain constants can be imported from UniEvent or Net::SockAddr or from IO::Socket. By default it is AF_UNSPEC and socket creation is postponed until call to connect() or accepting connection.

open($sock)

Open an existing file descriptor as TCP handle; it is expected that $sock is valid stream socket.

Socket is checked for connectivity and appropriate properties (readable, writable, connected, established, ...) are set.

May return error

bind($host, $port, [$hints = defaults], [$flags])

Bind the handle to an address, determined by $host, and the specified $port.

The $host can be a domain name, human-readable IP address or special string *, which means "bind to every available network interface on the host".

$port can be 0 in which case handle will be bound to a some available port. It can later be inspected via

    say $tcp->sockaddr->port;

If $host is a domain name, it is synchronously resolved to address using the specified $hints, see UniEvent::Resolver for the details.

$flags is the flags for binding. The only supported flag for now is UE::Tcp::IPV6ONLY in which case dual-stack support is disabled and only IPv6 is used.

May return error

bind_addr($addr, $flags)

Bind the handle to an address. $addr can be either a Net::SockAddr object or perl-style packed address (what sockaddr_in returns). For details on $flags see bind().

May return error

connect(\%params)

Start connection process to the specified endpoint. Endpoint is specified in params as either host/port or address.

params is a hashref with the following parameters (the only required is one of host+port or addr):

host

Can be a domain name or human-readable IP address. If it is a domain name then asynchronous resolve will be made before connecting.

port

hints

Used as hints during resolving (when host is a domain name). See UniEvent::Resolver for the details.

use_cache

Use resolver cache or not during resolving (when host is a domain name). See UniEvent::Resolver for the details.

Default is true.

addr

Use this address as an endpoint. Can be either a Net::SockAddr object or perl-style packed address (what sockaddr_in returns). If provided then host, port, hints and use_cache are ignored.

timeout

Timeout in seconds for the whole connection process (may be fractional). This includes possible resolving process, establishing tcp connection and possible SSL handshake if in use (i.e. full time until connect_event() is called). See UniEvent::Stream.

Default is 0 (no timeout).

callback

One-shot callback to be called upon completion of the connecting process. See "connect_event()" in UniEvent::Stream for signature.

The method returns immediately and provides UniEvent::Request::Connect as the result, i.e. actual connection will be performed later durning even loop run.

connect($host, $port, [$callback])

More efficient version of

    $tcp->connect({host => $host, port => $port, callback => $callback})

connect($host, $port, $timeout, [$callback])

More efficient version of

    $tcp->connect({host => $host, port => $port, timeout => $timeout, callback => $callback})

connect_addr($addr, [$callback])

More efficient version of

    $tcp->connect({addr => $addr, callback => $callback})

connect_addr($addr, $timeout, [$callback])

More efficient version of

    $tcp->connect({addr => $addr, timeout => $timeout, callback => $callback})

set_nodelay($enable)

Enables (disables) TCP_NODELAY, which disables(enables) Nagle’s algorithm on the handle.

May return error

set_keepalive($enable, $delay)

Enable / disable TCP keep-alive. $delay is the initial delay in seconds, ignored when enable is false.

May return error

set_simultaneous_accepts($enable)

Enable / disable simultaneous asynchronous accept requests that are queued by the operating system when listening for new TCP connections.

This setting is used to tune a TCP server for the desired performance. Having simultaneous accepts can significantly improve the rate of accepting connections (which is why it is enabled by default) but may lead to uneven load distribution in multi-process setups.

May return error

sockaddr()

Returns address (as Net::SockAddr object) of the local endpoint.

If socket is not connected, undef is returned.

May return error

peeraddr()

Returns address (as Net::SockAddr object) of the remote (peer) endpoint.

If socket is not connected, undef is returned.

May return error

dump()

Returns string indentifying the Tcp Handle. To be used for debugging purposes.

FUNCTIONS

pair([$loop = default])

pair(\%params)

Creates pair of connected UniEvent::Tcp handles in a cross-platform way.

First argument is either $loop, or hashref with the following parameters:

type

Defaults to UniEvent::SOCK_STREAM.

protocol

Defaults to UniEvent::PF_UNSPEC.

handle1

handle2

If supplied, will use and connect these tcp handles and instead of creating new ones.

They must be in a "clean" state (i.e. just created or after reset).

loop

Defaults to default loop

Returns list of two Tcp handles. Will throw on errors.

cpanm UniEvent

perl -MCPAN -e shell
install UniEvent