Browse files

Document signal handler classes, and create an example from which to …

…excerpt.
  • Loading branch information...
1 parent fae7c01 commit d204ea6e35362a62c2d81ca0a6b91ab8e44a9182 @rcaputo committed Apr 22, 2010
Showing with 96 additions and 47 deletions.
  1. +21 −0 eg/eg-39-signals.pl
  2. +32 −24 lib/Reflex/PID.pm
  3. +43 −23 lib/Reflex/Signal.pm
View
21 eg/eg-39-signals.pl
@@ -0,0 +1,21 @@
+# Watch signals a few different ways.
+
+use warnings;
+use strict;
+use lib qw(../lib);
+
+use Reflex::Signal;
+use Reflex::Callbacks qw(cb_coderef);
+use ExampleHelpers qw(eg_say);
+
+eg_say("Process $$ is waiting for SIGUSR1 and SIGUSR2.");
+
+my $usr1 = Reflex::Signal->new(
+ name => "USR1",
+ on_signal => cb_coderef { eg_say("Got SIGUSR1.") },
+);
+
+my $usr2 = Reflex::Signal->new( name => "USR2" );
+while ($usr2->wait()) {
+ eg_say("Got SIGUSR2.");
+}
View
56 lib/Reflex/PID.pm
@@ -30,13 +30,12 @@ sub stop_watching {
}
1;
-# TODO - Document.
__END__
=head1 NAME
-Reflex::PID - Observe the exit of a subprocess, via handling SIGCHLD.
+Reflex::PID - Observe the exit of a subprocess by its SIGCHLD signal.
=head1 SYNOPSIS
@@ -71,38 +70,47 @@ Reflex::PID - Observe the exit of a subprocess, via handling SIGCHLD.
=head1 DESCRIPTION
-Reflex::PID waits for a child process to exit, then announces the fact
-by emitting a "signal" event.
+Reflex::PID waits for a particular child process to exit. It emits a
+"signal" event with information about the child process when it has
+detected the child has exited.
-TODO - Complete the documentation, including the parameters of the
-signal event.
+Since Reflex::PID waits for a particular process ID, it's pretty much
+useless afterwards. Consider pairing it with Reflex::Collection if
+you have to maintain several transient processes.
-=head1 GETTING HELP
+Reflex::PID extends Reflex::Signal to handle a particular kind of
+signal---SIGCHLD.
-L<Reflex/GETTING HELP>
+TODO - However, first we need to make Reflex::PID objects stop
+themselves and emit "stopped" events when they're done. Otherwise
+Reflex::Collection won't know when to destroy them.
-=head1 ACKNOWLEDGEMENTS
+=head2 Public Events
-L<Reflex/ACKNOWLEDGEMENTS>
+=head3 signal
+
+Reflex::PID's "signal" event includes two named parameters. "pid"
+contains the process ID that exited. "exit" contains the process'
+exit value---a copy of C<$?> at the time the process exited. Please
+see L<perlvar/"$?"> for more information about that special Perl
+variable.
=head1 SEE ALSO
-L<Reflex> and L<Reflex/SEE ALSO>
+L<Moose::Manual::Concepts>
-=head1 BUGS
+L<Reflex>
+L<Reflex::Signal>
+L<Reflex::POE::Wheel::Run>
+L<Reflex/ACKNOWLEDGEMENTS>
+L<Reflex/ASSISTANCE>
+L<Reflex/AUTHORS>
L<Reflex/BUGS>
-
-=head1 CORE AUTHORS
-
-L<Reflex/CORE AUTHORS>
-
-=head1 OTHER CONTRIBUTORS
-
-L<Reflex/OTHER CONTRIBUTORS>
-
-=head1 COPYRIGHT AND LICENSE
-
-L<Reflex/COPYRIGHT AND LICENSE>
+L<Reflex/BUGS>
+L<Reflex/CONTRIBUTORS>
+L<Reflex/COPYRIGHT>
+L<Reflex/LICENSE>
+L<Reflex/TODO>
=cut
View
66 lib/Reflex/Signal.pm
@@ -101,7 +101,6 @@ sub DEMOLISH {
}
1;
-# TODO - Document.
__END__
@@ -111,45 +110,66 @@ Reflex::Signal - Generic signal observer and base class for specific ones.
=head1 SYNOPSIS
-TODO - Sorry, not yet. This class works (see the source for
-Reflex::PID, which extends it), but the API is not firm.
+As a callback:
-=head1 DESCRIPTION
+ use Reflex::Signal;
+ use Reflex::Callbacks qw(cb_coderef);
-Reflex::Signal is a general signal observer. Objects may use it to be
-notified when the OS sends signals. It may also be extended to handle
-nuanced semantics of more specific signals.
+ my $usr1 = Reflex::Signal->new(
+ name => "USR1",
+ on_signal => cb_coderef { print "Got SIGUSR1.\n" },
+ );
-TODO - Complete the API.
+As a promise:
-TODO - Complete the documentation.
+ my $usr2 = Reflex::Signal->new( name => "USR2" );
+ while ($usr2->wait()) {
+ print "Got SIGUSR2.\n";
+ }
-=head1 GETTING HELP
+May also be used with observers, and Reflex::Trait::Observer, but
+those use cases aren't shown here.
-L<Reflex/GETTING HELP>
+=head1 DESCRIPTION
-=head1 ACKNOWLEDGEMENTS
+Reflex::Signal is a general signal observer. It may be used to notify
+programs when they are sent a signal via kill.
-L<Reflex/ACKNOWLEDGEMENTS>
+=head2 Public Attributes
-=head1 SEE ALSO
+=head3 name
-L<Reflex> and L<Reflex/SEE ALSO>
+"name" defines the name (or number) of an interesting signal.
+The Reflex::Signal object will emit events when it detects that the
+process has been given that signal.
-=head1 BUGS
+=head2 Public Methods
-L<Reflex/BUGS>
+None at this time. Destroy the object to stop it.
-=head1 CORE AUTHORS
+=head2 Public Events
-L<Reflex/CORE AUTHORS>
+Reflex::Signal and its subclasses emit just one event: "signal".
+Generic signals have no additional information, but specific ones may.
+For example, Reflex::PID (SIGCHLD) includes a process ID and
+information about its exit.
-=head1 OTHER CONTRIBUTORS
+=head1 SEE ALSO
-L<Reflex/OTHER CONTRIBUTORS>
+L<Moose::Manual::Concepts>
-=head1 COPYRIGHT AND LICENSE
+L<Reflex>
+L<Reflex::PID>
+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

0 comments on commit d204ea6

Please sign in to comment.