Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 204 lines (142 sloc) 4.859 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203
package Reflex::Stream;

use Moose;
extends 'Reflex::Base';

has handle => (
is => 'rw',
isa => 'FileHandle',
required => 1
);

with 'Reflex::Role::Streaming' => {
handle => 'handle',
method_put => 'put',
method_stop => 'stop',
cb_error => 'on_error',
cb_data => 'on_data',
cb_closed => 'on_closed',
ev_error => 'error',
ev_data => 'data',
ev_closed => 'closed',
};

1;

__END__

=head1 NAME

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

=head1 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}";
}

=head1 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.

=head2 Public Attributes

=head3 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).

=head2 Public Methods

Reflex::Role::Streaming provides all of Reflex::Stream's methods.
Reflex::Stream however renames them to make more sense in a class.

=head3 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 L<Reflex::Role::Streaming/method_put> for details.

=head2 Callbacks

=head3 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.

=head3 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.

=head3 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.

=head2 Public Events

Reflex::Stream emits stream-related events, naturally.

=head3 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 L</on_closed> for more details.

=head3 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 L</on_data> for more details.

=head3 error

Reflex::Stream emits "error" when any of a number of calls fails.

See L</on_error> for more details.

=head1 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.

=head1 SEE ALSO

L<Reflex>
L<Reflex::Listener>
L<Reflex::Connector>
L<Reflex::UdpPeer>

L<Reflex/ACKNOWLEDGEMENTS>
L<Reflex/ASSISTANCE>
L<Reflex/AUTHORS>
L<Reflex/BUGS>
L<Reflex/BUGS>
L<Reflex/CONTRIBUTORS>
L<Reflex/COPYRIGHT>
L<Reflex/LICENSE>
L<Reflex/TODO>

=cut
Something went wrong with that request. Please try again.