Permalink
Browse files

Document Reflex::Client.

  • Loading branch information...
1 parent 4fb52d9 commit 0a9a05be7ac6059ad4bd19e5f55c8155b1f6cf9d @rcaputo committed Apr 21, 2010
Showing with 108 additions and 5 deletions.
  1. +108 −5 lib/Reflex/Client.pm
View
@@ -1,7 +1,7 @@
# A simple socket client. Generic enough to be used for INET and UNIX
# sockets, although we may need to specialize for each kind later.
-# TODO - This is a simple strawman implementation. It will need
+# TODO - This is a simple strawman implementation. It needs
# refinement.
package Reflex::Client;
@@ -43,20 +43,23 @@ sub on_connector_success {
sub on_connector_failure {
my ($self, $args) = @_;
- warn "$args->{errfun} error $args->{errnum}: $args->{errstr}\n";
$self->stop();
+ # TODO - Emit rather than warn.
+ warn "$args->{errfun} error $args->{errnum}: $args->{errstr}\n";
}
sub on_connection_closed {
my ($self, $args) = @_;
- warn "server closed connection.\n";
$self->stop();
+ # TODO - Emit rather than warn.
+ warn "server closed connection.\n";
}
sub on_connection_failure {
my ($self, $args) = @_;
- warn "$args->{errfun} error $args->{errnum}: $args->{errstr}\n";
$self->stop();
+ # TODO - Emit rather than warn.
+ warn "$args->{errfun} error $args->{errnum}: $args->{errstr}\n";
}
# This odd construct lets us rethrow a low-level event as a
@@ -75,4 +78,104 @@ after stop => sub {
};
1;
-# TODO - Document.
+
+__END__
+
+=head1 NAME
+
+Reflex::Client - A non-blocking socket client.
+
+=head1 SYNOPSIS
+
+This is a complete working TCP echo client. It's the version of
+eg/eg-35-tcp-client.pl available at the time of this writing.
+
+ use lib qw(../lib);
+
+ {
+ package TcpEchoClient;
+ use Moose;
+ extends 'Reflex::Client';
+
+ sub on_client_connected {
+ my ($self, $args) = @_;
+ $self->connection()->put("Hello, world!\n");
+ };
+
+ sub on_client_data {
+ my ($self, $args) = @_;
+
+ # Not chomped.
+ warn "got from server: $args->{data}";
+
+ # Disconnect after we receive the echo.
+ $self->stop();
+ }
+ }
+
+ TcpEchoClient->new(
+ remote_addr => '127.0.0.1',
+ remote_port => 12345,
+ )->run_all();
+
+=head1 DESCRIPTION
+
+Reflex::Client is a high-level base class for non-blocking socket
+clients. As with other Reflex::Object classes, this one may be
+subclassed, composed with "has", or driven with condvar-like syntax.
+
+=head2 Attributes
+
+Reflex::Client extends (and includes the attributes of)
+Reflex::Connector, which extends Reflex::Handle. It also provides its
+own attributes.
+
+=head3 protocol
+
+The "protocol" attribute contains the name of a class that will handle
+I/O for the client. It contains "Reflex::Stream" by default.
+
+Protocol classes should extend Reflex::Stream or at least follow its
+interface.
+
+=head2 Public Methods
+
+Reflex::Client extends Reflex::Handle, but it currently provides no
+additional methods.
+
+=head2 Events
+
+Reflex::Client emits some of its own high-level events based on its
+components' activities.
+
+=head3 connected
+
+Reflex::Client emits "connected" to notify consumers when the client
+has connected, and it's safe to begin sending data.
+
+=head3 data
+
+Reflex::Client emits stream data with the "data" event. This event is
+provided by Reflex::Stream. Please see L<Reflex::Stream/data> for the
+most current documentation.
+
+=head1 EXAMPLES
+
+eg/eg-35-tcp-client.pl subclasses Reflex::Client as TcpEchoClient.
+
+=head1 SEE ALSO
+
+L<Reflex>
+L<Reflex::Client>
+
+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

0 comments on commit 0a9a05b

Please sign in to comment.