view release on metacpan or  search on metacpan

lib/Carrot/Continuity/Coordination/Episode./documentation/Episode-en.pod  view on Meta::CPAN

=pod

=head1 NAME

Carrot::Continuity::Coordination::Episode - manage series of asynchronous events

=head1 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;

=head1 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 L<AnyEvent>, L<EV>, L<Event>, L<EventLib>, L<IO::Async>, L<IO-Multiplex>, L...


=head1 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 asynchro...

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->status

The double linkage is extra effort, but once done, event programming is easy.

=head2 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 events

To 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...

=head1 Targets

An event is I<generated by a source> and I<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 ...

When an event occurs, a method of an object is called. It shouldn't be too surprising that Carrot::Continuity::Coordination::Episode I<delivers events to instances>. That is a considerable overhead compared to subroutine callbacks, however, it's prob...

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...

=head1 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.

=head1 AUTHOR

Winfried Trumper E<lt>pub+perl(a)wt.tuxomania.netE<gt>

=head1 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.

=head1 SEE ALSO

L<AnyEvent>, L<EV>, L<Event>, L<EventLib>, L<IO::Async>, L<IO-Multiplex>, L<Net::Daemon>, L<Net-Server>, L<Net::FTPServer>, L<NetServer::Generic>, L<POE>, L<Qt>, and L<Tk>.

=cut