NAME
Carrot::Continuity::Coordination::Episode - manage series of asynchronous events
SYNOPSIS
# See Carrot::Continuity::Coordination::Episode::Synopsis for a longer example
use Carrot::Continuity::Coordination::Episode;
my $loop = Carrot::Continuity::Coordination::Episode::Loop->constructor;
$loop->run;WARNINGS
This is an experimental module. It hasn't been thoroughly tested, making the probability of fatal bugs quiet high. The sole goal of the release is to document the current development.
The documentation is not keeping up with the development speed and carries fragments from various stages of development.
In addition to the stage of the development, be warned that there are many competitors, which are much more mature and which might be better suited for your purposes. Namely AnyEvent, EV, Event, EventLib, IO::Async, IO-Multiplex, Net::Daemon, Net-Server, Net::FTPServer, NetServer::Generic, or POE. Obviously none of them convinced me, although launching the twelveth attempt to asynchronous event programming for Perl feels funny.
DESCRIPTION
Carrot::Continuity::Coordination::Episode provides a rather minimalistic OO interface to asynchronous events, plus those synchronous events which can be directly derived from them. You won't find a general NFA (one which isn't attached to an asynchronos event). You will also miss resource management features for built-in collaborative multitasking.
Delivery is done via method calls only, which implies a double linking between instances. In the following informal code, an instance has to keep a reference to the instance of the next lower step:
$client->connect
$session->request
$connection->syswrite
$connection->sysread
$session->parse
$client->statusThe double linkage is extra effort, but once done, event programming is easy.
The Loop
Events can be broadly put into two classes: synchronous and asynchronous. An approximate definition would be that asynchronous events come from outside the running program, and the origin of the synchronous events lie within the program.
The four standard sources for asynchronous events are time, signals, availability of file-like IO and user interaction. These require a so called event loop to be active.
During the event loop the program waits for any of the defined events to happen. In Carrot::Continuity::Coordination::Episode the loop object is monadic, which means that $loop is always the same instance, so you can pull it out anywhere you like.
my $loop = Carrot::Continuity::Coordination::Episode::Loop->constructor;
$loop->run(\$continue_flag); # await asynchronous eventsTo run the loop, call the method run. It takes one mandatory parameter, which is a scalar reference for loop control. As long as the scalar is true, the loop continues. However, the loop always completes the current round, there is no early break out.
Targets
An event is generated by a source and delivered to a target. If you set up a target, it will find its source automatically. Thus sources are not discussed at this point. Bringing a target to live is normally done in two steps. First the target is created by setting a callback and a trigger value. Then the target is activated. The explicit activation aids in controlling the series of events.
When an event occurs, a method of an object is called. It shouldn't be too surprising that Carrot::Continuity::Coordination::Episode delivers events to instances. That is a considerable overhead compared to subroutine callbacks, however, it's probably an overhead you need if you're still reading this document.
Delivering events as method calls has the side effect of keeping references to instances. You are well advised to always deactivate your events after use, otherwise the referenced instance stays alive and receives events. To be on the safe side, you might want to cancel the events in the DESTROY method (a destructor-like thing).
KNOWN BUGS AND LIMITATIONS
This is the first public release.
The Off-Topic directory OT contains some classes which might get replaced with a suitable solution from CPAN sooner or later.
AUTHOR
Winfried Trumper <pub+perl(a)wt.tuxomania.net>
COPYRIGHT AND LICENSE
Copyright (C) 2009, 2010 Winfried Trumper
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
SEE ALSO
AnyEvent, EV, Event, EventLib, IO::Async, IO-Multiplex, Net::Daemon, Net-Server, Net::FTPServer, NetServer::Generic, POE, Qt, and Tk.