NAME

Event - Event loop processing

WARNING

THIS IS EXPERIMENTAL CODE AND IS LIKELY TO CHANGE A CONSIDERABLE AMOUNT BEFORE IT IS RELEASED FOR GENERAL USE.

SYNOPSIS

use Event;

# initialize application

Event->Loop;

# and some callback will call
Event->exit;

DESCRIPTION

EVENT TYPES

idle

Event->idle( \&idle );

Call &idle when the loop is idle.

atexit

$e = Event->atexit( \&cleanup )

Call &cleanup when the event loop is about to exit. If after registering an atexit handler it is not required, the the cancel method can be called on $e.

watchvar

    $e = Event->watchvar(
	-variable => \$var,
	-async    => 0,
	-callback => \&watcher,
    );

Call &watcher when $var is changed. If -async is true then &watcher will be called immediately, otherwise the call to &watcher will be pushed onto the event queue.

When called &watcher will be passed $e as the first argument, &watcher may the call the cancel method to stop any future changes to $var creating events.

timer

    $e = Event->timer(
	-after    => 10,
	-at	  => time + 10,
	-interval => 2,
	-callback => \&timeout
    );

Call &timeout either after a given delay or at a given time (-after and -at are mutually exclusive). Then optionally call &timeout at given intervals.

When called &timeout will be passed $e as the first argument, and the time that the event was triggered as the second argument. &timeout may the call the cancel method on $e to stop any future timer events, or if -interval was not given and -after was then &timeout may call the again method on $e which will cause the event to re-occur, the time at which the event will re-occur is the value given by -after added to the time the event was triggered. Due to lags in the event loop calling the callback, this time may already be in the past, in which case the event will be queued immediately

io

    $e = Event->io(
	-handle => $sock,
	-events => POLLREAD,
	-callback => \&ready
    );

Call &ready when $sock has data to be read. -event can take any combination of the constants that are accepted by IO::Poll.

When called &ready is passed $e as the first argument, $handle as the second argument and the events that happened as the third argument. &ready may call the cancel method on $e to stop any future event handling on $handle

signal

    $e = Event->signal(
	-signal => 'INT',
	-callback => \&interrupt
    );

Call &interrupt when an INT signal is received. -signal accepts any signal name except CHLD, see below.

When called &interrupt will be passed $e as the first argument and the name of the signal as the second. &interrupt amy call the cancel method on $e to stop any future events being caught.

process

    $e = Event->process(
	-pid => $pid,
	-callback => \&reap
    );

Call &reap when the child process with pid $pid exits. If $pid is not given then &reap will be called for any process that does not have it's own event handler.

When called &reap will be passed $e as the first parameter, the process id of the child as the second and the exit status of the child as the third. &reap may call the cancel method on $e to stop future process events, this is only of use on event handlers where -pid is not specified.

FUTURE ENHANCEMENTS

    # generate an event when we can successfully run an op
    $e = Event->semaphore(
	-semaphore => $sem,
	-op => $op,
	-callback => \&gotit
    );
    
    # generate an event when the msg queue is/is not empty
    $e = Event->msg(
	-msg => $msg,
	-callback => \&doit
    );
    

AUTHOR

Graham Barr <gbarr@pobox.com>

COPYRIGHT

Copyright (c) 1997 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.