=head1 TITLE

Timers and Timeouts

=head1 VERSION

  Maintainer: Uri Guttman <uri@sysarch.com>
  Date: 10 Aug 2000
  Mailing List: perl6-language-flow@perl.org
  Number: 87
  Version: 1
  Status: Developing

=head1 ABSTRACT

This RFC will discuss supporting multiple independent timers and
timeouts for asynchronous I/O events and exiting eval blocks.

=head1 DESCRIPTION

Currently the only asynchronous timer mechanism in Perl is the alarm
signal. It has many flaws including being delivered unsafely and that
there is only one of them (which precludes nesting calls with their own
timeouts).

Under the asynchronous I/O (AIO) system all calls which support a
callback can also have an optional timeout. This event has a simple
common set of attribute/value arguments that can be used with any AIO
call. When no activity occurs on that AIO object before the timeout
period ends, the timeout is triggered and a callback is made. When any
activity occurs, the timeout is reset to its initial period (which can
also be done with the timeout_reset method). Standalone timeouts with no
AIO object can be created for use as independent timers.

Timers can be used to break out of any AIO operation and even out of
eval blocks by having the callback execute die (or quit or whatever). So
you can nest eval blocks and have control over how long each level takes
to run. Also this means no more collisions with sharing alarm calls.

=head1 IMPLEMENTATION

There are no syntactical changes needed for timeouts. All AIO calls will
be able to handle these additional optional arguments:

	timeout		=>	<number in seconds. float is OK>
	timeout_cb	=>	<timeout callback. see callback RFC>
	timeout_method	=>	<method to call other then the default>
	timeout_repeat	=>	<times to repeat>

The timeout arguments is in seconds but a float value can be used to get
fractions. The callback argument is the same as all the others in the
AIO system, it can be a coderef, an object or a class name. If you pass
in a timeout_method, that will be used as the callback. If the repeat
argument is passed the timeout will repeat that many times and forever
with the value -1.

Here is a typical AIO call with timeouts:

package Foo ;
	$aio->read_event( cb => 'Foo', timeout => 5 ) ;

sub READABLE {

	my( $self ) = @_ ;

	my $cnt = $aio->read( $buffer, 1024 ) ;
}

sub READ_EVENT_TIMEOUT {

	print "nothing to read\n" ;
}


The default callback name for timeouts will be the AIO operation name
in upper case and _TIMEOUT appended to it. So the default methods for
read and connect are READ_TIMEOUT and CONNECT_TIMEOUT

Timers not associated with an AIO object can be created firectly with
this call:

	$timer = AIO::Timer->new( timeout => 5, repeat => -1,
				  cb => sub{ print "annoying, isn't it!\n" }
	) ;


=head1 IMPACT

It has to be emphasized that all timing in this RFC is a minimum
time. There is no guarantee for any speed of delivery of the
event. Supporting event priorities is a possibility to improve the
delivery speed some.

This requires one of the AIO delivery methods (event loops, mailboxes,
in line) to be enabled. See the use aio RFC.

=head1 UNKNOWNS

=head1 REFERENCES

Event.pm		- XS based event loop module.

RFC #47			- Universal Asynchronous I/O (the moby one)