Reflex - Class library for flexible, reactive programs.
This document describes version 0.100, released on April 02, 2017.
The distribution includes a few different versions of this synopsis. See eg/eg-18-synopsis-no-moose.pl if you don't like Moose. See eg/eg-32-promise-tiny.pl if you prefer promises (condvar-like). See eg/eg-36-coderefs-tiny.pl if you prefer coderefs and/or closures.
{ package App; use Moose; extends 'Reflex::Base'; use Reflex::Interval; use Reflex::Trait::Watched qw(watches); watches ticker => ( isa => 'Reflex::Interval', setup => { interval => 1, auto_repeat => 1 }, ); sub on_ticker_tick { print "tick at ", scalar(localtime), "...\n"; } } exit App->new()->run_all();
Reflex is a class library that assists with writing reactive (AKA event-driven) programs. Reflex uses Moose internally, but it doesn't enforce programs to use Moose's syntax.
Those who enjoy Moose should find useful Reflex's comprehensive suite of reactive roles.
Reflex is considered "reactive" because it's an implementation of the reactor pattern. http://en.wikipedia.org/wiki/Reactor_pattern
Reactive objects provide responses to interesting (to them) stimuli. For example, an object might be waiting for input from a client, a signal from an administrator, a particular time of day, and so on. The App object in the SYNOPSIS is waiting for timer tick events. It generates console messages in response to those events.
Here an Echoer class emits "pong" events in response to ping() commands. It uses Moose's extends(), but it could about as easily use warnings, strict, and base instead. Reflex::Base gets its emit() method from Reflex::Role::Reactive.
package Echoer; use Moose; extends 'Reflex::Base'; sub ping { my ($self, $args) = @_; print "Echoer was pinged!\n"; $self->emit( -name => "pong" ); }
The next object uses Echoer. It creates an Echoer and pings it to get started. It also reacts to "pong" events by pinging the Echoer again. Reflex::Trait::Watched (via its exported watches() declarative syntax) implicitly watches the object in echoer(), mapping its "pong" event to the on_echoer_pong() method.
package Pinger; use Moose; extends 'Reflex::Base'; use Reflex::Trait::Watched qw(watches); watches echoer => ( isa => 'Echoer', default => sub { Echoer->new() }, ); sub BUILD { my $self = shift; $self->echoer->ping(); } sub on_echoer_pong { my $self = shift; print "Pinger got echoer's pong!\n"; $self->echoer->ping(); }
Then the Pinger would be created and run.
Pinger->new()->run_all();
A complete, runnable version of this example is in the distribution as eg/eg-37-ping-pong.pl.
Reflex supports any conceivable callback type, even the simple ones: plain old coderefs. You don't need to write objects to handle events.
Here we'll start a periodic timer and handle its ticks with a simple callback. The program is still reactive. Every second it prints "timer ticked" in response Reflex::Interval's events.
my $t = Reflex::Interval->new( interval => 1, auto_repeat => 1, on_tick => sub { say "timer ticked" }, ); $t->run_all();
A complete, runnable version of the above example is available as eg/eg-36-tiny-coderefs.pl in the distribution.
Callback haters are not left out. Reflex objects may also be used as asynchronous event generators. The following example is identical in function to the previous coderef callback example, but it doesn't use callbacks at all.
It may not be obvious that the same emit() method drives all of Reflex's forms of callback. The same Reflex::Interval class can be used in many different ways.
use Reflex::Interval; my $t = Reflex::Interval->new( interval => 1, auto_repeat => 1, ); while (my $event = $t->next()) { say "next() returned an event (@$event)"; }
Reflex itself contains some convenience methods for cleaner semantics.
Run all active Reflex objects until they destruct.
# (Omitted: First you'll need to create some Reflex objects.) Reflex->run_all(); exit;
Reflex bundles a number of helpful base classes to get things started.
The basic modules upon which most everything else is built.
Reflex provides adapters for nearly every kind of callback that exists, including condvar-like promises that allow Reflex objects to be used inline without callbacks at all.
POE provides over 400 modules for various useful things. Reflex can work with them using these adapters.
It's often useful to manage collections of like-typed modules, such as connections or jobs.
Event driven programs most often react to I/O of some sort. These modules provide reactive I/O support.
Modules that provide signal support, including SIGCHLD for child process management.
Timer management has been relatively overlooked so far. We'll get to it eventually, and you're welcome to help.
Reflex also implements signal/slot style object interaction, through emit() and watch() methods. These traits were inspired by Smalltalk's watchable object attributes.
Thank you for volunteering to assist with this project. You can find like-minded people in a few places, in descending order of preference. Or, oh, wait, maybe you wanted assistance using it? We'll help you, too. :)
See irc.perl.org #reflex for help with Reflex.
See irc.perl.org #poe for help with POE and Reflex.
See irc.perl.org #moose for help with Moose.
Support is officially available from POE's mailing list as well. Send a blank message to poe-subscribe@perl.org to join.
The Reflex package also has helpful examples which may serve as a tutorial until Reflex is documented more.
We appreciate your feedback, bug reports, feature requests, patches and kudos. You may enter them into our request tracker by following the instructions at https://rt.cpan.org/Dist/Display.html?&Queue=Reflex.
We also accept e-mail at bug-Reflex@rt.cpan.org.
Rocco Caputo, RCAPUTO on CPAN.
Reflex is open source, and we welcome involvement.
Chris Fedde, CFEDDE on CPAN
https://github.com/rcaputo/reflex
http://gitorious.org/reflex
Please browse the source for the TODO marker. Some are visible in the documentation, and others are sprinlked around in the code's comments.
Also see "TODO.otl" in docs in the distribution. This is a Vim Outliner file with the current roadmap and progress.
Set up Dist::Zilla to reduce technical debt and make releasing code fun again.
Copyright 2009-2011 by Rocco Caputo.
Reflex is free software. You may redistribute and/or modify it under the same terms as Perl itself.
Please see those modules/websites for more information related to this module.
, , the Reflex and Reflexive namespaces on CPAN.
Ohlo -
CIA -
You can find documentation for this module with the perldoc command.
perldoc Reflex
The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources.
MetaCPAN
A modern, open-source CPAN search engine, useful to view POD in HTML format.
http://metacpan.org/release/Reflex
Search CPAN
The default CPAN search engine, useful to view POD in HTML format.
http://search.cpan.org/dist/Reflex
RT: CPAN's Bug Tracker
The RT ( Request Tracker ) website is the default bug/issue tracking system for CPAN.
https://rt.cpan.org/Public/Dist/Display.html?Name=Reflex
AnnoCPAN
The AnnoCPAN is a website that allows community annotations of Perl module documentation.
http://annocpan.org/dist/Reflex
CPAN Ratings
The CPAN Ratings is a website that allows community ratings and reviews of Perl modules.
http://cpanratings.perl.org/d/Reflex
CPAN Forum
The CPAN Forum is a web forum for discussing Perl modules.
http://cpanforum.com/dist/Reflex
CPANTS
The CPANTS is a website that analyzes the Kwalitee ( code metrics ) of a distribution.
http://cpants.cpanauthors.org/dist/Reflex
CPAN Testers
The CPAN Testers is a network of smokers who run automated tests on uploaded CPAN distributions.
http://www.cpantesters.org/distro/R/Reflex
CPAN Testers Matrix
The CPAN Testers Matrix is a website that provides a visual overview of the test results for a distribution on various Perls/platforms.
http://matrix.cpantesters.org/?dist=Reflex
CPAN Testers Dependencies
The CPAN Testers Dependencies is a website that shows a chart of the test results of all dependencies for a distribution.
http://deps.cpantesters.org/?module=Reflex
You can email the author of this module at poe-subscribe@perl.org asking for help with any problems you have.
poe-subscribe@perl.org
You can get live help by using IRC ( Internet Relay Chat ). If you don't know what IRC is, please read this excellent guide: http://en.wikipedia.org/wiki/Internet_Relay_Chat. Please be courteous and patient when talking to us, as we might be busy or sleeping! You can join those networks/channels and get help:
irc.perl.org
You can connect to the server at 'irc.perl.org' and join this channel: #reflex to get help.
Please report any bugs or feature requests by email to bug-reflex at rt.cpan.org, or through the web interface at https://rt.cpan.org/Public/Bug/Report.html?Queue=Reflex. You will be automatically notified of any progress on the request by the system.
bug-reflex at rt.cpan.org
The code is open to the world, and available for you to hack on. Please feel free to browse it and play with it, or whatever. If you want to contribute patches, please send me a diff or prod me to pull from your repository :)
git clone git://github.com/rcaputo/reflex.git
You can make new bug reports, and view existing ones, through the web interface at http://rt.cpan.org/Public/Dist/Display.html?Name=Reflex.
Rocco Caputo <rcaputo@cpan.org>
irc.perl.org channel #moose and #poe. The former for assisting in learning their fine libraries, sometimes against everyone's better judgement. The latter for putting up with lengthy and sometimes irrelevant design discussion for oh so long.
This software is copyright (c) 2017 by Rocco Caputo.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
The latest version of this module is available from the Comprehensive Perl Archive Network (CPAN). Visit http://www.perl.com/CPAN/ to find a CPAN site near you, or see https://metacpan.org/module/Reflex/.
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
3 POD Errors
The following errors were encountered while parsing the POD:
Nested L<> are illegal. Pretending inner one is X<...> so can continue looking for other errors.
To install Reflex, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Reflex
CPAN shell
perl -MCPAN -e shell install Reflex
For more information on module installation, please visit the detailed CPAN module installation guide.