Permalink
Browse files

Document! Oh, gods, it burns!

  • Loading branch information...
1 parent 376ab5f commit 122cbcc1b1c67738ad7ab3775982051210fd7d73 @rcaputo committed Jul 15, 2010
Showing with 432 additions and 8 deletions.
  1. +114 −0 lib/Reflex/Interval.pm
  2. +138 −1 lib/Reflex/Role/Interval.pm
  3. +9 −7 lib/Reflex/Role/Timeout.pm
  4. +87 −0 lib/Reflex/Timeout.pm
  5. +84 −0 lib/Reflex/Wakeup.pm
View
@@ -18,3 +18,117 @@ with 'Reflex::Role::Interval' => {
};
1;
+
+__END__
+
+=head1 NAME
+
+Reflex::Interval - A stand-alone multi-shot periodic callback
+
+=head1 SYNOPSIS
+
+As with all Reflex objects, Reflex::Interval may be used in many
+different ways.
+
+Inherit it and override its on_tick() callback, with or without using
+Moose.
+
+ package App;
+ use Reflex::Interval;
+ use base qw(Reflex::Interval);
+
+ sub on_tick {
+ print "tick at ", scalar(localtime), "...\n";
+ shift()->repeat();
+ }
+
+Run it as a promise that generates periodic events. All other Reflex
+objects will also be running while C<<$pt->next()>> is blocked.
+
+ my $pt = Reflex::Interval->new(
+ interval => 1 + rand(),
+ auto_repeat => 1,
+ );
+
+ while (my $event = $pt->next()) {
+ eg_say("promise timer returned an event ($event->{name})");
+ }
+
+Plain old callbacks:
+
+ my $ct = Reflex::Interval->new(
+ interval => 1,
+ auto_repeat => 1,
+ on_tick => sub { print "coderef callback triggered\n" },
+ );
+ Reflex->run_all();
+
+And so on. See Reflex, Reflex::Base and Reflex::Role::Reactive for
+details.
+
+=head1 DESCRIPTION
+
+Reflex::Interval invokes a callback after a specified interval of time
+has passed, and then after every subsequent interval of time.
+Interval timers may be stopped and started. Their timers may be
+automatically or manually repeated.
+
+=head2 Public Attributes
+
+=head3 interval
+
+Implemented and documented by L<Reflex::Role::Interval/interval>.
+
+=head3 auto_repeat
+
+Implemented and documented by L<Reflex::Role::Interval/auto_repeat>.
+
+=head3 auto_start
+
+Implemented and documented by L<Reflex::Role::Interval/auto_start>.
+
+=head2 Public Callbacks
+
+=head3 on_tick
+
+Implemented and documented by L<Reflex::Role::Interval/cb_tick>.
+
+=head2 Public Methods
+
+=head3 repeat
+
+Implemented and documented by L<Reflex::Role::Interval/method_repeat>.
+
+=head3 start
+
+Implemented and documented by L<Reflex::Role::Interval/method_start>.
+
+=head3 stop
+
+Implemented and documented by L<Reflex::Role::Interval/method_stop>.
+
+=head1 EXAMPLES
+
+TODO - Many. Link to them.
+
+=head1 SEE ALSO
+
+L<Reflex>
+L<Reflex::Role>
+L<Reflex::Role::Interval>
+L<Reflex::Role::Timeout>
+L<Reflex::Role::Wakeup>
+L<Reflex::Timeout>
+L<Reflex::Wakeup>
+
+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
View
@@ -6,6 +6,7 @@ attribute_parameter interval => "interval";
attribute_parameter auto_repeat => "auto_repeat";
attribute_parameter auto_start => "auto_start";
+method_parameter method_start => qw( start name _ );
method_parameter method_stop => qw( stop interval _ );
method_parameter method_repeat => qw( repeat interval _ );
callback_parameter cb_tick => qw( on interval tick );
@@ -86,4 +87,140 @@ role {
__END__
-TODO - Document.
+=head1 NAME
+
+Reflex::Role::Interval - set a periodic, recurring timer
+
+=head1 SYNOPSIS
+
+ package Reflex::Interval;
+
+ use Moose;
+ extends 'Reflex::Base';
+
+ has interval => ( isa => 'Num', is => 'ro' );
+ has auto_repeat => ( isa => 'Bool', is => 'ro', default => 1 );
+ has auto_start => ( isa => 'Bool', is => 'ro', default => 1 );
+
+ with 'Reflex::Role::Interval' => {
+ interval => "interval",
+ auto_start => "auto_start",
+ auto_repeat => "auto_repeat",
+ cb_tick => "on_tick",
+ method_start => "start",
+ method_stop => "stop",
+ method_repeat => "repeat",
+ };
+
+ 1;
+
+=head1 DESCRIPTION
+
+Reflex::Role::Interval adds a periodic timer and callback to a class.
+It's parameterized, so it can be consumed multiple times to add more
+than one interval timer to the same class.
+
+In the SYNOPSIS, the Reflex::Interval class consumes a single
+Reflex::Role::Interval. Reflex::Interval provides some data in the
+form of interval(), auto_repeat() and auto_start(). The role provides
+a callback to the on_tick() method, which is also provided by the
+role. The role also provides some control methods, start(), stop()
+and repeat().
+
+The general rules and conventions for Reflex paramaeterized roles are
+covered in L<Reflex::Role>.
+
+=head2 Attribute Parameters
+
+Attribute parameters specify the names of attributes in the consumer
+that control the role's behavior.
+
+=head3 interval
+
+C<interval> names an attribute in the consumer that must hold the
+role's interval, in seconds. The role will trigger a callback
+every interval() seconds, if the C<auto_repeat> attribute is true.
+
+C<interval> is a Reflex::Role "key" attribute. The interval
+attribute's name is used in the default names for the role's internal
+and public attributes, methods and callbacks.
+
+=head3 auto_repeat
+
+Interval timers will repeat automatically if the value of the
+attribute named in C<auto_repeat> is true. Otherwise, repeat() must
+be called to trigger the next interval callback, C<interval> seconds
+after repeat() is called.
+
+=head3 auto_start
+
+Interval timers will automatically start if the value of the attribute
+named in C<auto_start> is true. Otherwise, the class consuming this
+role must call the role's start method, named in C<method_start>.
+
+=head2 Callback Parameters
+
+Callback parameters specify the names of methods in the consumer that
+will be called when the role notifies the class of events.
+
+=head3 cb_tick
+
+C<cb_tick> sets the name of the tick callback method, which must be
+implemented by this role's consumer. C<cb_tick> is optional, and will
+default to the catenation of "on_", the name of the interval
+attribute, and "_tick".
+
+Reflex::Role::Interval provides a default callback that will emit the
+"tick" event and repeat the timer if C<<$self->$auto_repeat()>>
+evaluates to true.
+
+=head2 Method Parameters
+
+Method parameters generally specify the names of methods the role will
+provide to modify the role's behavior.
+
+=head3 method_repeat
+
+Reflex::Role::Interval provides a method to manually trigger
+repetition of the interval timer. This method exists in case
+C<auto_repeat> evaluates to false. The repeat method name may be
+overridden by C<method_repeat>'s value. By default, the repeat method
+will be "repeat_" prepended to the name of the interval attribute.
+
+=head3 method_start
+
+Reflex::Role::Interval provides a method to start the interval timer,
+which is vital for cases when C<auto_start> evaluates to false. The
+start method name may be overridden by C<method_start>'s value. By
+default, the start method will be "start_" prepended to the name of
+the interval attribute.
+
+=head3 method_stop
+
+Reflex::Role::Interval provides a method to stop the interval timer.
+This method will be flattened into the consuming class, per Moose.
+C<method_stop> allows the role's consumer to define the name of that
+method. By default, the stop method's name will be "stop_" prepended
+to the name of the interval attribute.
+
+=head1 EXAMPLES
+
+L<Reflex::Timeout> is one example of using Reflex::Role::Timeout.
+
+=head1 SEE ALSO
+
+L<Reflex>
+L<Reflex::Interval>
+L<Reflex::Role>
+
+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
View
@@ -152,8 +152,9 @@ to wait for input and a longer timeout to wait for authentication.
=head3 auto_start
-Timeouts will automatically start unless the value of the attribute
-named in C<auto_start> is false.
+Timeouts will automatically start if the value of the attribute
+named in C<auto_start> is true. Otherwise, the class consuming this
+role must call the role's start method, named in C<method_start>.
=head3 method_stop
@@ -172,14 +173,15 @@ The stop method neither takes parameters nor returns anything.
=head3 method_reset
C<method_reset> allows the role's consumer to override the default
-reset method name. The default is C<"stop_${delay_name}">, where
-$delay_name is the attribute name provided in the C<delay> parameter.
+reset method name. The default is C<"reset_${timeout_name}">, where
+$timeout_name is the attribute name provided in the C<timeout>
+parameter.
All Reflex methods accept a hashref of named parameters. Currently
the reset method accepts one named parameter, "delay". The value of
-"delay" must be the new time to trigger a callback. If "delay" isn't
-provided, the timeout callback will happen at the previous time set by
-this module.
+"delay" must be the new timeout to trigger a callback. If "delay"
+isn't provided, the timeout callback will happen at the previous time
+set by this module.
$self->reset_name( { delay => 60 } );
View
@@ -29,3 +29,90 @@ with 'Reflex::Role::Timeout' => {
};
1;
+
+__END__
+
+=head1 NAME
+
+Reflex::Timeout - A stand-alone single-shot delayed callback
+
+=head1 SYNOPSIS
+
+ #!/usr/bin/env perl
+
+ use warnings;
+ use strict;
+
+ use Reflex::Timeout;
+
+ my $to = Reflex::Timeout->new(
+ delay => 1,
+ on_done => \&handle_timeout,
+ );
+
+ Reflex->run_all();
+ exit;
+
+ sub handle_timeout {
+ print "got timeout\n";
+ $to->reset();
+ }
+
+=head1 DESCRIPTION
+
+Reflex::Timeout invokes a callback after a specified amount of time
+has elapsed. Timeouts may be stopped, restarted, or reset so they
+must again wait the full delay period. Resetting is especially
+useful, for example whenever input arrives.
+
+=head2 Public Attributes
+
+=head3 delay
+
+Implemented and documented by L<Reflex::Role::Timeout/delay>.
+
+=head2 Public Callbacks
+
+=head3 on_done
+
+Implemented and documented by L<Reflex::Role::Timeout/cb_timeout>.
+
+=head2 Public Methods
+
+=head3 reset
+
+Implemented and documented by L<Reflex::Role::Timeout/method_reset>.
+
+=head3 start
+
+Implemented and documented by L<Reflex::Role::Timeout/method_start>.
+
+=head3 stop
+
+Implemented and documented by L<Reflex::Role::Timeout/method_stop>.
+
+=head1 EXAMPLES
+
+TODO - Link to them.
+
+=head1 SEE ALSO
+
+L<Reflex>
+L<Reflex::Role>
+L<Reflex::Role::Interval>
+L<Reflex::Role::Timeout>
+L<Reflex::Role::Wakeup>
+L<Reflex::Interval>
+L<Reflex::Wakeup>
+
+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.

0 comments on commit 122cbcc

Please sign in to comment.