Permalink
Browse files

Add preliminary documentation to the last three modules.

  • Loading branch information...
1 parent e932bd7 commit 297a698cb5fe16f7b1747feb10c247bdbcba0cb8 @rcaputo committed Apr 23, 2010
Showing with 293 additions and 84 deletions.
  1. +75 −27 lib/Reflex/POE/Postback.pm
  2. +155 −32 lib/Reflex/POE/Wheel.pm
  3. +63 −25 lib/Reflex/POE/Wheel/Run.pm
@@ -52,7 +52,6 @@ sub DESTROY {
}
1;
-# TODO - Document.
__END__
@@ -62,51 +61,100 @@ Reflex::POE::Postback - Communicate with POE components expecting postbacks.
=head1 SYNOPSIS
-# Not a complete example. Please see eg-11-poco-postback.pl in the
-# examples for a working one.
+Not a complete example. Please see eg-11-poco-postback.pl in the eg
+directory for a complete working program.
- $self->component->request(
- Reflex::POE::Postback->new(
- $self, "on_component_result", { cookie => 123 }
- ),
+ my $postback = Reflex::POE::Postback->new(
+ $self, "on_component_result", { cookie => 123 }
);
-TODO - Needs a better example.
-
=head1 DESCRIPTION
-Reflex::POE::Postback creates an object that's compatible with the POE
-postback. These may be given to POE components that require postbacks to
-work.
+Reflex::POE::Postback creates an object that's substitutes for
+POE::Session postbacks. When invoked, however, they sent events back
+to the object and method (and with optional continuation data)
+provided during construction.
-TODO - Complete the documentation.
+Reflex::POE::Postback was designed to interact with POE modules that
+want to respond via caller-provided postbacks. Authors are encouraged
+to encapsulate POE interaction within Reflex objects. Most users
+should therefore not need use Reflex::POE::Postback (or other
+Reflex::POE helpers) directly.
-=head1 GETTING HELP
+=head2 Public Methods
-L<Reflex/GETTING HELP>
+=head3 new
-=head1 ACKNOWLEDGEMENTS
+new() constructs a new Reflex::POE::Postback object, which will be a
+blessed coderef following POE's postback convention.
-L<Reflex/ACKNOWLEDGEMENTS>
+It takes three positional parameters: the required object and method
+to invoke when the postback is called, and an optional context that
+will be passed verbatim to the callback.
-=head1 SEE ALSO
+=head2 Callback Parameters
-L<Reflex> and L<Reflex/SEE ALSO>
+=head3 context
-=head1 BUGS
+The "context" callback parameter contains whatever was supplied to the
+Reflex::POE::Postback when it was created. In the case of the
+SYNOPSIS, that would be:
-L<Reflex/BUGS>
+ sub on_component_result {
+ my ($self, $arg) = @_;
+
+ # Displays: 123
+ print $arg->{context}{cookie}, "\n";
+ }
+
+=head3 response
+
+"response" contains an array reference that holds whatever was passed
+to the postback. If we assume this postback call:
+
+ $postback->(qw(eight six seven five three oh nine));
+
+Then the callback might look something like this:
-=head1 CORE AUTHORS
+ sub on_component_result {
+ my ($self, $arg) = @_;
-L<Reflex/CORE AUTHORS>
+ # Displays: nine
+ print "$arg->{response}[-1]\n";
+ }
-=head1 OTHER CONTRIBUTORS
+=head1 CAVEATS
-L<Reflex/OTHER CONTRIBUTORS>
+Reflex::POE::Postback must produce objects as blessed coderefs. This
+is something I don't know how to do yet with Moose, so Moose isn't
+used. Therefore, Reflex::POE::Postback doesn't do a lot of things one
+might expect after working with other Reflex objects.
-=head1 COPYRIGHT AND LICENSE
+If Moose can be used later, it may fundamentally change the entire
+interface. The goal is to do this only once, however.
-L<Reflex/COPYRIGHT AND LICENSE>
+It might be nice to map positional response parameters to named
+parameters. Reflex::POE::Wheel does this, but it remains to be seen
+whether that's considered cumbersome.
+
+=head1 SEE ALSO
+
+L<Moose::Manual::Concepts>
+
+L<Reflex>
+L<Reflex::POE::Event>
+L<Reflex::POE::Session>
+L<Reflex::POE::Wheel::Run>
+L<Reflex::POE::Wheel>
+
+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
@@ -5,7 +5,7 @@ use Scalar::Util qw(weaken);
use POE::Wheel;
has wheel => (
- isa => 'Object|Undef',
+ isa => 'Maybe[POE::Wheel]',
is => 'rw',
);
@@ -88,7 +88,6 @@ sub _deliver {
}
1;
-# TODO - Document.
__END__
@@ -98,60 +97,184 @@ Reflex::POE::Wheel - Base class for POE::Wheel wrappers.
=head1 SYNOPSIS
-# Not a complete example. Consider looking at the source for
-# Reflex::POE::Wheel::Run, which subclasses Reflex::POE::Wheel.
-
-TODO - Need an example.
+There is no concise synopsis at this time. Setting up a new
+Reflex::POE::Wheel is rather involved. The source for
+L<Reflex::POE::Wheel::Run> may serve as an example.
=head1 DESCRIPTION
-Reflex::POE::Wheel is a base class for POE::Wheel wrappers.
-Subclasses will configure Reflex::POE::Wheel to provide the proper
-POE::Wheel constructor parameters. Additional configuration converts
-the POE::Wheel events into Reflex::Object events.
+Reflex::POE::Wheel is a base class for Reflex objects that wrap and
+observe POE::Wheel objects. Subclasses define a handful of methods
+that describe the wheels they wrap. Reflex::POE::Wheel will use the
+configuration to validate constructor parameters, map wheel events to
+Reflex events, and map positional callback parameters to named ones.
-Methods are not yet converted automatically. It seems more sensible
-to provide a native Reflex::Object interface, although one could
-certainly use Moose's "handles" attribute option to pass the wheel's
-methods through the wrapper.
+It's rather handy once you get used to it.
+
+=head2 Public Attributes
+
+=head3 wheel
+
+Currently Reflex::POE::Wheel exposes the raw POE::Wheel via its
+wheel() attribute. This will be undefined if the wheel hasn't been
+set up yet.
-TODO - Complete the documentation.
+=head2 Public Methods
-=head2 wheel_id
+=head3 wheel_id
-Return the internal wheel's ID.
+The wheel_id() method returns the ID of the POE::Wheel being managed.
+C<< $foo->wheel()->ID() >> can also be used instead.
-=head2 demolish_wheel
+=head3 demolish_wheel
Cause the internal wheel to be demolished. Provided as a method since
some wheels may require special handling.
-=head1 GETTING HELP
+=head2 Required Subclass Methods
-L<Reflex/GETTING HELP>
+These subclass methods are used to configure subclasses for their
+chosen POE::Wheel objects.
-=head1 ACKNOWLEDGEMENTS
+=head3 event_to_index
-L<Reflex/ACKNOWLEDGEMENTS>
+event_to_index() maps POE::Wheel events to consecutive integer event
+IDs. event_emit_names() will provide Reflex-friendly event names
+based on the event IDs. event_param_names() will provide parameter
+names that correspond to the wheel's positional parameters.
-=head1 SEE ALSO
+This mapping is from Reflex::POE::Wheel::Run. It will make more sense
+in the context of event_emit_names() and event_param_names().
-L<Reflex> and L<Reflex/SEE ALSO>
+ sub event_to_index {
+ return(
+ {
+ StdinEvent => 0,
+ StdoutEvent => 1,
+ StderrEvent => 2,
+ ErrorEvent => 3,
+ CloseEvent => 4,
+ },
+ );
+ }
-=head1 BUGS
+=head3 event_emit_names
+
+event_emit_names() returns an array reference that maps
+Reflex::POE::Wheel's event IDs to Reflex-friendly event names.
+
+Here's an example from Reflex::POE::Wheel::Run. The wheel's
+StdinEvent (ID 0) is emitted as "stdin" (the 0th element in
+event_emit_names()). StdoutEvent becomes "stdout", and so on.
+
+ sub event_emit_names {
+ return(
+ [
+ 'stdin', # StdinEvent
+ 'stdout', # StdoutEvent
+ 'stderr', # StderrEvent
+ 'error', # ErrorEvent
+ 'closed', # ClosedEvent
+ ],
+ );
+ }
-L<Reflex/BUGS>
+=head3 event_param_names
+
+event_param_names() returns an array reference that maps
+Reflex::POE::Wheel's event IDs to Reflex-friendly lists of parameter
+names. The underlying POE::Wheel's positional parameters will be
+mapped to these names before the Reflex object emits them.
+
+Here's yet another example from Reflex::POE::Wheel::Run. StdinEvent
+and StdoutEvent each return two parameters. The Reflex object will
+emit their ARG0 as the named parameter "output", and ARG1 becomes the
+named parameter "wheel_id".
+
+ sub event_param_names {
+ return(
+ [
+ [ "wheel_id" ],
+ [ "output", "wheel_id" ],
+ [ "output", "wheel_id" ],
+ [ "operation", "errnum", "errstr", "wheel_id", "handle_name" ],
+ [ "wheel_id" ],
+ ]
+ );
+ }
+
+=head3 wheel_class
+
+wheel_class() returns a simple string---the class name of the wheel to
+construct.
+
+=head3 valid_params
+
+The valid_params() method returns a hash reference keyed on valid
+constructor parameters. Values don't matter at this time.
+Reflex::POE::Wheel uses this hash reference to pre-validate
+construction of underlying POE::Wheel objects.
+
+POE::Wheel::Run takes quite a lot of parameters, most of which are
+optional.
+
+ sub valid_params {
+ return(
+ {
+ CloseOnCall => 1,
+ Conduit => 1,
+ Filter => 1,
+ Group => 1,
+ NoSetPgrp => 1,
+ NoSetSid => 1,
+ Priority => 1,
+ Program => 1,
+ ProgramArgs => 1,
+ StderrDriver => 1,
+ StderrFilter => 1,
+ StdinDriver => 1,
+ StdinFilter => 1,
+ StdioDriver => 1,
+ StdioFilter => 1,
+ StdoutDriver => 1,
+ StdoutFilter => 1,
+ User => 1,
+ }
+ );
+ }
+
+=head1 CAVEATS
+
+The demolish() name is heading towards deprecation in favor of
+something shorter and more widely recognized, perhaps stop(). The
+jury is still out, however.
-=head1 CORE AUTHORS
+Methods are not yet converted automatically. It seems more sensible
+to provide a native Reflex::Object interface. On the other hand, it
+may be possible for Moose's "handles" attribute option to pass the
+wheel's methods through the wrapper. More investigation is required.
-L<Reflex/CORE AUTHORS>
+wheel() or wheel_id() will be deprecated, depending upon which is
+considered redundant.
-=head1 OTHER CONTRIBUTORS
+=head1 SEE ALSO
-L<Reflex/OTHER CONTRIBUTORS>
+L<Moose::Manual::Concepts>
-=head1 COPYRIGHT AND LICENSE
+L<Reflex>
+L<Reflex::POE::Event>
+L<Reflex::POE::Postback>
+L<Reflex::POE::Session>
+L<Reflex::POE::Wheel::Run>
-L<Reflex/COPYRIGHT AND LICENSE>
+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
Oops, something went wrong. Retry.

0 comments on commit 297a698

Please sign in to comment.