NAME

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

VERSION

version 0.005

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_stream_data {
                my ($self, $args) = @_;
                $self->put($args->{data});
        }

        sub on_stream_failure {
                my ($self, $args) = @_;
                warn "$args->{errfun} error $args->{errnum}: $args->{errstr}\n";
                $self->emit( event => "stopped", args => {} );
        }

        sub on_stream_closed {
                my ($self, $args) = @_;
                $self->emit( event => "stopped", args => {} );
        }

        sub DEMOLISH {
                print "EchoStream demolished as it should.\n";
        }

        1;

Since it extends Reflex::Object, 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->wait();
        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 uses Reflex::Handle to read data from the handle when it arrives, and to write data to the handle as space becomes available. Data that cannot be written right away will be buffered until Reflex::Handle says the handle can accept more.

Public Attributes

Reflex::Stream inherits attributes from Reflex::Handle. Please see the other module for the latest documentation.

One Reflex::Handle attribute to be wary of is rd(). It defaults to false, so Reflex::Stream objects don't start off ready to read data. This is subject to change.

No other public attributes are defined.

Public Methods

Reflex::Stream adds its own public methods to those that may be inherited by Refex::Handle.

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::Handle says it's safe to write again.

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.

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.

failure

Reflex::Stream emits "failure" when any of a number of calls fails. This event's parameters include:

• data - Undefined, since no data could be read.

• errnum - The numeric value of $! at the time of error.

• errstr - The string value of $! at the time of error.

• errfun - A brief description of the function call that failed.

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 condvar-esque 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

cpanm Reflex

perl -MCPAN -e shell
install Reflex