NAME
Reflex::Stream - Buffered, translated I/O on non-blocking handles.
VERSION
version 0.056
SYNOPSIS
This is a complete Reflex::Stream subclass. It echoes whatever it receives back to the sender. Its error handlers are compatible with Reflex::Collection.
package EchoStream;
use Moose;
extends 'Reflex::Stream';
sub on_data {
my ($self, $args) = @_;
$self->put($args->{data});
}
sub on_error {
my ($self, $args) = @_;
warn "$args->{errfun} error $args->{errnum}: $args->{errstr}\n";
$self->stopped();
}
sub DEMOLISH {
print "EchoStream demolished as it should.\n";
}
1;Since it extends Reflex::Base, it may also be used like a condavr or promise. This incomplte example comes from eg/eg-38-promise-client.pl:
my $stream = Reflex::Stream->new(
handle => $socket
rd => 1,
);
$stream->put("Hello, world!\n");
my $event = $stream->next();
if ($event->{name} eq "data") {
print "Got echo response: $event->{arg}{data}";
}
else {
print "Unexpected event: $event->{name}";
}DESCRIPTION
Reflex::Stream reads from and writes to a file handle, most often a socket. It is almost entirely implemented in Reflex::Role::Streaming. That role's documentation contains important details that won't be covered here.
Public Attributes
handle
Reflex::Stream implements a single attribute, handle, that must be set to the stream's file handle (which can be a socket or something).
Public Methods
Reflex::Role::Streaming provides all of Reflex::Stream's methods. Reflex::Stream however renames them to make more sense in a class.
put
The put() method writes one or more chunks of raw octets to the stream's handle. Any data that cannot be written immediately will be buffered until Reflex::Role::Streaming can write it later.
Please see "method_put" in Reflex::Role::Streaming for details.
Callbacks
on_closed
Subclasses may define on_closed() to be notified when the remote end of the stream has closed for output. No further data will be received after receipt of this callback.
on_closed() receives no parameters of note.
The default on_closed() callback will emit a "closed" event. It will also call stopped().
When overriding this callback, please be sure to call stopped(), which is provided by Reflex::Role::Collectible. Calling stopped() is vital for collectible objects to be released from memory when managed by Reflex::Collection.
on_data
on_data() will be called whenever Reflex::Stream receives data. It will include one named parameter in $_[1], "data", containing raw octets received from the stream.
sub on_data {
my ($self, $param) = @_;
print "Got data: $param->{data}\n";
}The default on_data() callback will emit a "data" event.
on_error
on_error() will be called if an error occurs reading from or writing to the stream's handle. Its parameters are the usual for Reflex:
sub on_error {
my ($self, $param) = @_;
print "$param->{errfun} error $param->{errnum}: $param->{errstr}\n";
}The default on_error() callback will emit a "error" event. It will also call stopped().
When overriding this callback, please be sure to call stopped(), which is provided by Reflex::Role::Collectible. Calling stopped() is vital for collectible objects to be released from memory when managed by Reflex::Collection.
Public Events
Reflex::Stream emits stream-related events, naturally.
closed
The "closed" event indicates that the stream is closed. This is most often caused by the remote end of a socket closing their connection.
See "on_closed" for more details.
data
The "data" event is emitted when a stream produces data to work with. It includes a single parameter, also "data", containing the raw octets read from the handle.
See "on_data" for more details.
error
Reflex::Stream emits "error" when any of a number of calls fails.
See "on_error" for more details.
EXAMPLES
eg/EchoStream.pm in the distribution is the same EchoStream that appears in the SYNOPSIS.
eg/eg-38-promise-client.pl shows a lengthy inline usage of Reflex::Stream and a few other classes.
SEE ALSO
Reflex Reflex::Listener Reflex::Connector Reflex::UdpPeer
"ACKNOWLEDGEMENTS" in Reflex "ASSISTANCE" in Reflex "AUTHORS" in Reflex "BUGS" in Reflex "BUGS" in Reflex "CONTRIBUTORS" in Reflex "COPYRIGHT" in Reflex "LICENSE" in Reflex "TODO" in Reflex