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.