NAME

Event - Event loop processing

WARNING

THIS IS EXPERIMENTAL AND IS LIKELY TO CHANGE BEFORE BEING DECLARED STABLE.

Thank you for your patience.

SYNOPSIS

    use Event;
    
    # initialize application
    
    my $ret = Event::Loop::Loop();
    
    # and some callback will call
    Event::Loop::exitLoop('ok');

DESCRIPTION

EVENTS

The following properties are common to all events. Each property may be prepended with a dash (-) or not depending on your preferance.

callback

Use either a code ref or an array containing an object and the method name.

count

The number of times the event has been queued. An event can be queued multiple times before it has time to be serviced. For example, many asyncronous signals can arrive before the associated event can be dequeued.

priority

A default priority is assigned to each event upon creation. The default depends on the type of the event. A +- offset from the default can be passed via the priority key. If the priority is a negative number the callback will be called immediately, otherwise it will be pushed onto the event queue. While it may seem advantageous to use a negative priorities, it defeats the purpose of even having an event queue in the first place.

now

Events can be queued manually with the now method. Any now additional arguments passed to now are forwarded to the event callback. You must provide whatever arguments your event handler is expecting since the now method bypasses the usual dispatch apparatus.

cancel

Cancelled events are not invoked.

EVENT TYPES

idle

    Event->idle(callback => \&idle);

Call &idle when the loop is idle.

watchvar

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

Call &watcher when $var is changed.

When called &watcher will be passed $e as the first argument.

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. 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, the re-queued timeout may already be in the past. If the 'hard' flags was set, the event will be queued for execution immediately. Otherwise, the new timeout will be calculated relative to the current time (this is the default).

io

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

Call &ready when $sock has data to be read. event takes one or more of 'r', 'w', or 'e'. These correspond to read, write, and exceptional data, respectively.

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 but this is only of use on event handlers where pid is not specified.

CALLBACK ARGUMENTS [DEPRECIATED]

The arguments passed to the event callback depends on the type of the event handler:

  io             $event
  process        $event, $pid, $status
  signal         $event, $name, $count
  timer          $event, $when
  watchvar       $event, $ref

Event::Loop API

$Now

Time::HiRes::time() cache for low-accuracy clients.

queueEvent

doOneEvent

Loop

exitLoop

PRIO_HIGH, PRIO_NORMAL, QUEUES

A COMMENT ON THE DESIGN

While object-oriented design has gained popularity in recent times, Event does not follow these ideas as strictly as it might. Performance cannot be sacrificed for theoretical beauty. Real beauty is to balance a solution to the requirements, without elaboration.

More documentation is needed.

DIRECTION

    # 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
    );
    

ALSO SEE

NetServer::ProcessTop

SUPPORT

This extension is discussed on the perl-loop@perl.org mailing list.

AUTHORS

Graham Barr <gbarr@pobox.com>, Joshua Pritikin <bitset@mindspring.com>

COPYRIGHT

Copyright © 1997-1998 Graham Barr & Joshua Nathaniel Pritikin. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Event

perl -MCPAN -e shell
install Event