/ 
Reflex-0.050
River stage one • 7 direct dependents • 7 total dependents
/ Reflex::Stream

NAME

Reflex::Stream - Buffered, translated I/O on non-blocking handles.

VERSION

version 0.050

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