Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Document Reflex::Stream.

  • Loading branch information...
commit cd734cf1a96797a0ee1811629f6cf038bb41a06f 1 parent 0a9a05b
@rcaputo authored
Showing with 145 additions and 1 deletion.
  1. +145 −1 lib/Reflex/Stream.pm
View
146 lib/Reflex/Stream.pm
@@ -136,4 +136,148 @@ sub _emit_failure {
}
1;
-# TODO - Document.
+
+__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_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}";
+ }
+
+=head1 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.
+
+=head2 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.
+
+=head2 Public Methods
+
+Reflex::Stream adds its own public methods to those that may be
+inherited by Refex::Handle.
+
+=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::Handle says it's safe to write again.
+
+=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.
+
+=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.
+
+=head3 failure
+
+Reflex::Stream emits "failure" when any of a number of calls fails.
+This event's parameters include:
+
+=over 2
+
+=item * data - Undefined, since no data could be read.
+
+=item * errnum - The numeric value of $! at the time of error.
+
+=item * errstr - The string value of $! at the time of error.
+
+=item * errfun - A brief description of the function call that failed.
+
+=back
+
+=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 condvar-esque 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
Please sign in to comment.
Something went wrong with that request. Please try again.