=pod

=head1 NAME

Object::Episode - manage series of asynchronous events

=head1 SYNOPSIS

	# See Object::Episode::Synopsis for a longer example

	use Object::Episode;
	my $loop = Object::Episode::Loop->new();
	$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<Net::Daemon>, L<Net-Server>, L<Net::FTPServer>, L<NetServer::Generic>, or L<POE>. Obviously none of them convinced me, although launching the twelveth attempt to asynchronous event programming for Perl feels funny.


=head1 DESCRIPTION

Object::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 objects. In the following informal code, an object has to keep a reference to the object 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 Object::Episode the loop object is monadic, which means that $loop is always the same object, so you can pull it out anywhere you like.

	my $loop = Object::Episode::Loop->new();
	$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 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 Object::Episode I<delivers events to objects>. 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 objects. You are well advised to always deactivate your events after use, otherwise the referenced object 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).

=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
