Document Reflex::Stream.

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