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

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

	sub evt_time_periodic	{ print STDERR "."; }
	sub evt_time_wallclock	{ print STDERR "W"; }
	sub evt_time_timeout	{ print STDERR "T"; kill(&POSIX::SIGUSR1, $PROCESS_ID); }
	sub evt_time_boundary	{ print STDERR "B"; }
	sub evt_signal_usr1	{ print STDERR "S\n"; ${$_[0]} = 0; }
	sub evt_poll_edge_test1	{ print STDERR "P$_[1]"; }
	}

=head1 DESCRIPTION

The purpose of the following example is to introduce Carrot::Continuity::Coordination::Episode with a fully functional piece of code. The class Carrot::Continuity::Coordination::Episode::Synopsis is shipped for this purpose only. Using the convenienc...

The example above should print '...................T.S' to the screen, with a one second delay between each output. Create and remove the file /tmp/any.txt to see a P. The USR1 signal sets the loop control to zero, effectively terminating the show. I...

The package Event_Demo is required, because Carrot::Continuity::Coordination::Episode is about instances, not classes. The $demo instance holds a loop control (a trivial scalar ref) and provides the callback methods (default names).

=head2 Public Interface

Punchy means, there is action upon a simple string. However, there is not much point in formatting and then (one subroutine call later) parsing a simple string. Instead, directly pass the values you have to the specific interfaces.

But there is nothing wrong with documenting the convenience interface. The first parameter is the instance to call back a hard-wired method name. The second parameter is recognized as follows: