NAME

IO::KQueue - perl interface to the BSD kqueue system call

SYNOPSIS

    my $kq = IO::KQueue->new();
    $kq->EV_SET($fd, EVFILT_READ, EV_ADD, 0, 5);
    
    my %results = $kq->kevent($timeout);

DESCRIPTION

This module provides a fairly low level interface to the BSD kqueue() system call, allowing you to monitor for changes on sockets, files, processes and signals.

Usage is very similar to the kqueue system calls, so you will need to have read and understood the kqueue man page. This document may seem fairly light on details but that is merely because the details are in the man page, and so I don't wish to replicate them here.

API

IO::KQueue->new()

Construct a new KQueue object (maps to the kqueue() system call).

$kq->EV_SET($ident, $filt, $flags, $fflags, $data, $udata)

e.g.:

  $kq->EV_SET(fileno($server), EVFILT_READ, EV_ADD, 0, 5);

Equivalent to the EV_SET macro followed immediately by a call to kevent() to set the event up.

Note that to watch for both read and write events you need to call this method twice - once with EVFILT_READ and once with EVFILT_WRITE - unlike epoll() and poll() these "filters" are not a bitmask.

Returns nothing. Throws an exception on failure.

The $fflags, $data and $udata params are optional.

$kq->kevent($timeout)

Poll for events on the kqueue. Timeout is in milliseconds. If timeout is ommitted then we wait forever until there are events to read. If timeout is zero then we return immediately.

Returns a list of arrayrefs which contain the kevent. The contents of the kevent are:

• $kevent->[KQ_IDENT]

• $kevent->[KQ_FILTER]

• $kevent->[KQ_FLAGS]

• $kevent->[KQ_FFLAGS]

• $kevent->[KQ_DATA]

• $kevent->[KQ_UDATA]

See the included tail.pl and chat.pl scripts for example usage, and see the kqueue man pages for full details.

CONSTANTS

For a list of exported constants see the source of Makefile.PL, or the kqueue man page. In addition the KQ_* entries of the kevent are also exported - see the list above.

LICENSE

This is free software. You may use it and distribute it under the same terms as Perl itself - i.e. either the Perl Artistic License, or the GPL version 2.0.

AUTHOR

Matt Sergeant, <matt@sergeant.org>

Copyright 2005 MessageLabs Ltd.

SEE ALSO

IO::Poll