NAME UniEvent::Stream - abstract base class for streaming handles

DESCRIPTION

The class shares common interface (and implementation) for the UniEvent::Tcp, UniEvent::Pipe and UniEvent::Tty handles.

The key feature of UniEvent::Stream that it is aimed to handle connected-oriented full-duplex messaging aka steaming, i.e., first, the connection should be established, and then traffic might flow independently in both directions.

To use SSL-version of the library, the use_ssl method should be invoced first, before binding/listening (for server) or before connecting (for client).

Examples of using streams can be seen in the examples directory, shipped within the module distribution.

METHODS

readable()

Returns true if the stream is readable.

writable()

Returns true if the stream is writable.

listening()

Returns true if listening has been started on the stream.

connecting()

Returns true if connecting has been initiated for the stream.

established()

Returns true if the previous (lower, physical) layer of the stream has succesfully connected to the peer. It is true, for example, when TCP connection has been established, but the possible SSL-hanshake is not been confirmed yet.

For handlers without SSL, the connected and established coincide.

connected()

Returns true if the next (high, logical) layer of the stream has succesfully connected to the peer. It is true, for example, when TCP connection has been established, and the SSL-hanshake has been confirmed.

For handlers without SSL, the connected and established coincide.

wantread()

Returns true if the stream is ready for reading incoming data.

shutting_down()

Returns true shutdown procedure has been initiated on the handle.

is_shut_down()

Returns true shutdown procedure has been finished on the handle.

write_queue_size()

Returns the amount of queued bytes waiting to be sent.

is_secure()

Returns true if the handler has SSL-context.

connection_factory($callback)

When handle is in the listening mode, it is possible to do custom incoming peer handle upgrade via the $callback. The $callback must return the stream handle object. For example, to inject custom field it can be done like:

my $server = UniEvent::Tcp->new;
$server->bind(...);
$server->listen();
...
$server->connection_factory(sub {
    my $client = shift;
    XS::Framework::obj2hv($client);
    $client->{my_data} = 'sample data';
    return $client;
});

connection_callback($code)

Sets the callback, which will be invoked during loop run, when the stream handle in listening mode accepts new client.

All previously set event listeners or callbacks are discarded.

connection_event()

Returns XS::Framework::CallbackDispatcher instance, where callback(s) can be assigned with. The callbacks will be invoked during loop run, when the stream handle in listening mode accepts new client

The C++ interface is:

void(const StreamSP& handle, const StreamSP& client, const ErrorCode& err);

On perl side it the callbacks will be called :

$callback->($server, $client, $error_code);

Multiple callbacks can be added via the XS::Framework::CallbackDispatcher interface.

connect_callback($code)

Sets the callback, which will be invoked during loop run, when the stream handle (client) successfully connects to a peer (i.e. connected() returns true).

All previously set event listeners or callbacks are discarded.

connect_event()

Returns XS::Framework::CallbackDispatcher instance, where callback(s) can be assigned with. The callbacks will be invoked during loop run, when the stream handle (client) successfully connects to a peer, (i.e. connected() returns true).

The C++ interface is:

void(const StreamSP& handle, const ErrorCode& err, const ConnectRequestSP& req);

On perl side it the callbacks will be called :

$callback->($handle, $error_code, $connect_request);

Multiple callbacks can be added via the XS::Framework::CallbackDispatcher interface.

read_callback($code)

Sets the callback, which will be invoked during loop run, when the handle has read piece of data from remote peer.

All previously set event listeners or callbacks are discarded.

read_event()

Returns XS::Framework::CallbackDispatcher instance, where callback(s) can be assigned with. The callbacks will be invoked during loop run, when the handle has read piece of data from remote peer.

The C++ interface is:

void(const StreamSP& handle, string& piece, const ErrorCode& err)

On perl side it the callbacks will be called :

$callback->($handle, $piece, $error_code);

Multiple callbacks can be added via the XS::Framework::CallbackDispatcher interface.

write_callback($code)

Sets the callback, which will be invoked during loop run, when the handle has wrote piece of data (previously queued for writing via write method).

All previously set event listeners or callbacks are discarded.

write_event()

Returns XS::Framework::CallbackDispatcher instance, where callback(s) can be assigned with. The callbacks will be invoked during loop run, when the handle has wrote piece of data (previously queued for writing via write method).

The C++ interface is:

void(const StreamSP& handle, const ErrorCode& err, const WriteRequestSP& req)

On perl side it the callbacks will be called :

$callback->($handle, $error_code, $write_request);

Multiple callbacks can be added via the XS::Framework::CallbackDispatcher interface.

shutdown_callback($code)

Sets the callback, which will be invoked during loop run, when the handle successfully shuts down. This happens when write requests are complete, and a peer confirmed it has received data (i.e. via ACK) and shutdown of the handle has been requested. If there are no data to write, and shutdown has been requested, the shutdown_callback will be invoked too.

The shutdown callback/event is opposite to eof callback/event.

All previously set event listeners or callbacks are discarded.

shutdown_event()

Returns XS::Framework::CallbackDispatcher instance, where callback(s) can be assigned with. The callbacks will be invoked during loop run, when the handle successfully shuts down. This happens when write requests are complete, and a peer confirmed it has received data (i.e. via ACK) and shutdown of the handle has been requested. If there are no data to write, and shutdown has been requested, the shutdown_callback will be invoked too.

The shutdown callback/event is opposite to eof callback/event.

The C++ interface is:

void(const StreamSP& handle, const ErrorCode& err, const ShutdownRequestSP& req);

On perl side it the callbacks will be called :

$callback->($handle, $error_code, $shutdown_request);

Multiple callbacks can be added via the XS::Framework::CallbackDispatcher interface.

eof_callback($callback)

Sets the callback, which will be invoked during loop run, when a peer of the handle shuts down, i.e. no more data will be received.

The eof callback/event is opposite to shutdown callback/event.

All previously set event listeners or callbacks are discarded.

eof_event()

Returns XS::Framework::CallbackDispatcher instance, where callback(s) can be assigned with. The callbacks will be invoked during loop run, when peer of the handle shuts down, i.e. no more data will be received.

The C++ interface is:

void(const StreamSP& handle);

On perl side it the callbacks will be called :

$callback->($handle);

Multiple callbacks can be added via the XS::Framework::CallbackDispatcher interface.

event_listener($delegate [, $weak = false])

Creates and returns wrapper around the $delegate object of arbitrary class, having the following methods:

$delegate->create_connection($handle);
$delegate->on_connection    ($handle, $peer_handle, $error_code       );
$delegate->on_connect       ($handle, $error_code,  $connect_request  );
$delegate->on_read          ($handle, $buffer,      $error_code       );
$delegate->on_write         ($handle, $error_code,  $write_request    );
$delegate->on_shutdown      ($handle, $error_code,  $shutdown_request );
$delegate->on_eof           ($handle);

The delegated object can be seen as alternative of setting indivitual callbacks or as a way of groupping them. The $delegate object can optionally be weakened.

listen([$callback = undef [, $backlog = 128]]) -> excepted<void, ErrorCode> ?

Start listening for incoming connections. $backlog indicates the number of connections the kernel might queue, same as listen(2). The connection $callback can be added if needed.

When a new peer connects, the connection callback/event is invoked.

true is returned in scalar context on success. Otherwise, in non-list context exception will be thrown. In list context (undef, $error_code) is returned in case of error.

read_start()

Instructs the stream to read data from an peer during loop iteration. It reads until eof or error condition are met, or until read_stop.

Read callback/event are invoked if new data is received.

read_stop()

Stop reading data from the stream.

write($data [, $write_callback = undef])

Writes $data to the stream. One-shot $write_callback will be invocked upon successful operation completion.

The UniEvent::Request::Write is returned.

shutdown([$timeout = 0 [, $shutdown_callback = undef]])

Shutdown the outgoing (write) side of a duplex stream. It waits for pending write requests to complete during $timeout (if it is non-zero). If timeout timer triggers, than all pending write requests are cancelled and the stream it shutdown by force.

The $shutdown_callback is one-shot callback invoked upon operation completion.

The UniEvent::Request::Shutdown is returned.

use_ssl([$ssl_context = undef])

Sets or resets $ssl_context on the stream. The ssl context can be created via the Net::SSLeay package, e.g.:

use Net::SSLeay;

my $SERV_CERT = "ca.pem";
my $serv_ctx = Net::SSLeay::CTX_new();
Net::SSLeay::CTX_use_certificate_file($serv_ctx, $SERV_CERT, &Net::SSLeay::FILETYPE_PEM) or die;
Net::SSLeay::CTX_use_PrivateKey_file($serv_ctx, "ca.key", &Net::SSLeay::FILETYPE_PEM) or die;
Net::SSLeay::CTX_check_private_key($serv_ctx) or die;
my $srv = UE::Tcp->new;
$srv->use_ssl($serv_ctx);

recv_buffer_size([$value = undef])

Gets or sets (if $value is defined) the size of the receive buffer that the operating system uses for the stream.

Returns the current size of buffer.

send_buffer_size([$value = undef])

Gets or sets (if $value is defined) the size of the send buffer that the operating system uses for the stream.

Returns the current size of buffer.

run_in_order($callback)

If there is any pending I/O requests, the $callback will be attached to the last one, and exected rigth upon I/O request completion, in the loop run context.

Otherwise, if there is no any pending I/O requests, the $callback will be executed immedialy in the caller context.

The main purpose of the method is to allow attach the execution of different one-shot "on completion" callbacks right after enqueing I/O operation.

The callback will be invoked as