view release on metacpan or  search on metacpan

lib/UniEvent/Stream.pod  view on Meta::CPAN

The example above is the same as

    $tcp->connect($host, $port, sub {
        $tcp->write("data", sub {
            $tcp->disconnect;
        });
    });

The only exception is when the only pending request is a connect request. In this case, connect request is immediately cancelled, and the stream disconnects.

NOTE: if you want to immediately disconnect the stream cancelling all pending requests, call L<UniEvent::Handle/"reset()"> or L<UniEvent::Handle/"clear()">



=head2 sockaddr()

Returns address (as L<Net::SockAddr> object) of the B<local> endpoint if possible.

If stream is not connected or not representable as sockaddr (windows named pipe, tty), undef is returned.

L<May return error|UniEvent/"OPTIONAL ERRORS">


=head2 peeraddr()

Returns address (as L<Net::SockAddr> object) of the B<remote> (peer) endpoint if possible.

If stream is not connected or not representable as sockaddr (windows named pipe, tty), undef is returned.

L<May return error|UniEvent/"OPTIONAL ERRORS">



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

Methods C<on_establish>, C<on_connection>, C<on_connect>, C<on_read>, C<on_write>, C<on_shutdown>, C<on_eof> will be called.

Event C<on_establish> is present only in event listener, not in event dispatcher version. It will be called (for client and server) when physical
connection is established (before possible SSL layer and so on).

See L<UniEvent/"EVENT LISTENER">


=head2 use_ssl([$ssl_context])

Enables SSL for the stream (adds SSL filter).

C<$ssl_context> can be created via L<Net::SSLeay> and may be omitted for clients if default behaviour is ok. For servers, ssl context is required.

    my $client = UE::Tcp->new;
    $client->use_ssl;
    $client->connect($host, $port);
    ...

For servers, SSL must be enabled on listening stream, not on individual connection streams. The same SSL context will be used for accepted streams.

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

Enabling or disabling (see C<no_ssl()>) SSL can only be done in certain moments:

=over

=item

For client streams, only before stream starts connecting or after it disconnects.

=item

For server stream, at any moment (further accepted connections will use SSL).

=item

For server connections (server-client streams), it is not possible as they are connected from the beginning and not used after disconnection.
You must call this method on server listening stream.

=back


=head2 no_ssl()

Disables SSL for the stream (removes SSL filter).
See C<use_ssl()> for details when this method can be called.


=head2 is_secure()

Returns C<true> if stream is using SSL.


=head2 run_in_order($callback)

Queues a callback to the stream. Callback will be invoked when all requests queued before this callback are done, but before requests queued after this callback
start executing.

    $tcp->connect($host, $port);
    $tcp->write("first");
    $tcp->run_in_order(sub { ... });
    $tcp->write("second");
    
In the example above, callback will be called after the stream is connected and sent first message. After calling callback, second message will be written.

In other words, C<run_in_order()> is the same as adding one more callback to the previous request.

Callback is invoked with a single argument - the stream object. 

=cut