IO::EventQueue
$Id: README,v 1.1 2003/03/28 19:21:56 xmath Exp $

INSTALLATION

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install

Module documentation:

NAME
    IO::EventQueue - Darwin Event Queue - wait for events on multiple
    sockets simultaneously - UNTESTED

SYNOPSIS
        # THIS MODULE HAS NOT YET BEEN TESTED AT ALL

        use IO::EventQueue ':all';

        watchevent EV_FD, fileno SOCK1, EV_RE;
        watchevent EV_FD, fileno SOCK2, EV_RE | EV_WR | EV_EX;

        my ($type, $fd, $rcnt, $wcnt, $ecnt, $eventbits) = waitevent;
        print "$rcnt bytes available on fd $fd\n"  if $eventbits & EV_RBYTES;

        if (my @ev = waitevent 2.5) { }     # wait at most 2.5 seconds

        modwatch EV_FD, $fd, EV_RE;         # change/reactivate event watch
        modwatch EV_FD, $fd, EV_RM;         # remove event watch

DESCRIPTION
    Provides perl access to the Event Queue on Mac OS X or Darwin, as an
    efficient and scalable replacement for 4-arg select().

    Early draft, completely untested. It could probably use a cleaner
    interface too.. something that doesn't involve manually managing fd
    numbers :-)

FUNCTIONS
    watchevent TYPE, REFNUM, EVENTMASK
        Add an event watch for given event source. The only type currently
        supported is EV_FD, with the "REFNUM" being the file descriptor of a
        socket. Returns true if successful, otherwise sets $! and returns
        false.

        The event mask consists of one or more of the bits EV_RD, RV_WR,
        EV_EX or'ed together; their meaning is analogous to 4-arg select().

        Calling watchevent when an event has already been installed will
        cause an error (EINVAL).

    modwatch TYPE, REFNUM, EVENTMASK
        Change the eventmask of an event watch. You need this to re-activate
        an event watch after receiving an event using "waitevent", which
        clears the event mask. You can also remove an event watch entirely
        by passing EV_RM as the event mask.

    waitevent TIMEOUT
    waitevent
        Wait for any watched event to occur, or until the timeout expires.
        The timeout is in seconds and may be fractional. If the timeout is
        undef or omitted, waitevent waits forever (or until interrupted by a
        signal).

        If an error or timeout occurs, waitevent returns an empty list and
        sets $! (to 0 for timeout). Otherwise it returns a 6-element list:
        (TYPE, REFNUM, RCNT, WCNT, ECNT, EVENTMASK). TYPE and REFNUM
        identify the event source (TYPE is always EV_FD currently).

        The returned event mask has one of the bits EV_RD, EV_WR, EV_EX set,
        and may optionally have one or more other event bits set, described
        below.

        The RCNT and WCNT might indicate something like how many bytes can
        be read / written (and perhaps RCNT might indicate how many
        connections are pending for the EV_RD|EV_RCONN event) but I haven't
        checked. ECNT is currently unused.

Event bits
    EV_RBYTES
        Data is available for reading data.

    EV_WBYTES
        Buffer space is available for writing data.

    EV_OOB
        Out of band data is available to be read.

    EV_RCLOSED
        Socket has been shutdown for reading.

    EV_WCLOSED
        Socket has been shutdown for writing.

    EV_RCONN
        An incoming connection is available to be accepted.

    EV_WCONN
        An asynchronous connect has successfully completed.

    EV_FIN
        The remote side has closed the connection. Data may still be
        available for reading, and you may still write data.

    EV_RESET
        The connection has been refused or ungracefully closed.

    EV_TIMEOUT
        An asynchronous operation has timed out.

KNOWN ISSUES
    Once again, this code is completely untested. As in, I haven't even
    called any of the functions a single time. I was just in the mood to
    write it.

    It compiles. :-)

AUTHOR
    Matthijs van Duin <xmath@cpan.org>

    Copyright (C) 2003 Matthijs van Duin. All rights reserved. This program
    is free software; you can redistribute it and/or modify it under the
    same terms as Perl itself.

