1package IO::KQueue;
2
3use strict;
4use vars qw($VERSION @ISA @EXPORT $AUTOLOAD $MAX_EVENTS);
5
6use DynaLoader ();
7use Exporter ();
8
9use Errno;
10
11BEGIN {
12$VERSION = '0.34';
13
14$MAX_EVENTS = 1000;
15
16@ISA = qw(Exporter DynaLoader);
17@EXPORT = qw(
18    EV_ADD
19    EV_DELETE
20    EV_ENABLE
21    EV_DISABLE
22    EV_ONESHOT
23    EV_CLEAR
24    EV_EOF
25    EV_ERROR
26    EVFILT_READ
27    EVFILT_WRITE
28    EVFILT_VNODE
29    EVFILT_PROC
30    EVFILT_SIGNAL
31    EVFILT_TIMER
32    EVFILT_FS
33    NOTE_LOWAT
34    NOTE_DELETE
35    NOTE_WRITE
36    NOTE_EXTEND
37    NOTE_ATTRIB
38    NOTE_LINK
39    NOTE_RENAME
40    NOTE_REVOKE
41    NOTE_EXIT
42    NOTE_FORK
43    NOTE_EXEC
44    NOTE_PCTRLMASK
45    NOTE_PDATAMASK
46    NOTE_TRACK
47    NOTE_TRACKERR
48    NOTE_CHILD
49    KQ_IDENT
50    KQ_FILTER
51    KQ_FLAGS
52    KQ_FFLAGS
53    KQ_DATA
54    KQ_UDATA
55);
56
57bootstrap IO::KQueue $VERSION;
58}
59
60use constant EV_ADD => (constant('EV_ADD'))[1];
61use constant EV_DELETE => (constant('EV_DELETE'))[1];
62use constant EV_ENABLE => (constant('EV_ENABLE'))[1];
63use constant EV_DISABLE => (constant('EV_DISABLE'))[1];
64use constant EV_ONESHOT => (constant('EV_ONESHOT'))[1];
65use constant EV_CLEAR => (constant('EV_CLEAR'))[1];
66use constant EV_EOF => (constant('EV_EOF'))[1];
67use constant EV_ERROR => (constant('EV_ERROR'))[1];
68use constant EVFILT_READ => (constant('EVFILT_READ'))[1];
69use constant EVFILT_WRITE => (constant('EVFILT_WRITE'))[1];
70use constant EVFILT_VNODE => (constant('EVFILT_VNODE'))[1];
71use constant EVFILT_PROC => (constant('EVFILT_PROC'))[1];
72use constant EVFILT_SIGNAL => (constant('EVFILT_SIGNAL'))[1];
73use constant EVFILT_TIMER => (constant('EVFILT_TIMER'))[1];
74use constant EVFILT_FS => (constant('EVFILT_FS'))[1];
75use constant NOTE_LOWAT => (constant('NOTE_LOWAT'))[1];
76use constant NOTE_DELETE => (constant('NOTE_DELETE'))[1];
77use constant NOTE_WRITE => (constant('NOTE_WRITE'))[1];
78use constant NOTE_EXTEND => (constant('NOTE_EXTEND'))[1];
79use constant NOTE_ATTRIB => (constant('NOTE_ATTRIB'))[1];
80use constant NOTE_LINK => (constant('NOTE_LINK'))[1];
81use constant NOTE_RENAME => (constant('NOTE_RENAME'))[1];
82use constant NOTE_REVOKE => (constant('NOTE_REVOKE'))[1];
83use constant NOTE_EXIT => (constant('NOTE_EXIT'))[1];
84use constant NOTE_FORK => (constant('NOTE_FORK'))[1];
85use constant NOTE_EXEC => (constant('NOTE_EXEC'))[1];
86use constant NOTE_PCTRLMASK => (constant('NOTE_PCTRLMASK'))[1];
87use constant NOTE_PDATAMASK => (constant('NOTE_PDATAMASK'))[1];
88use constant NOTE_TRACK => (constant('NOTE_TRACK'))[1];
89use constant NOTE_TRACKERR => (constant('NOTE_TRACKERR'))[1];
90use constant NOTE_CHILD => (constant('NOTE_CHILD'))[1];
91
92use constant KQ_IDENT => 0;
93use constant KQ_FILTER => 1;
94use constant KQ_FLAGS => 2;
95use constant KQ_FFLAGS => 3;
96use constant KQ_DATA => 4;
97use constant KQ_UDATA => 5;
98
99sub DESTROY {
100}
101
102sub AUTOLOAD {
103    my $sub = $AUTOLOAD;
104    (my $constname = $sub) =~ s/.*:://;
105    my ($err, $val) = constant($constname);
106    if (defined($err)) {
107        die $err;
108    }
109    eval "sub $sub () { $val }";
110    goto &$sub;
111}
112
1131;
114
115__END__
116
117=head1 NAME
118
119IO::KQueue - perl interface to the BSD kqueue system call
120
121=head1 SYNOPSIS
122
123    my $kq = IO::KQueue->new();
124    $kq->EV_SET($fd, EVFILT_READ, EV_ADD, 0, 5);
125
126    my %results = $kq->kevent($timeout);
127
128=head1 DESCRIPTION
129
130This module provides a fairly low level interface to the BSD kqueue() system
131call, allowing you to monitor for changes on sockets, files, processes and
132signals.
133
134Usage is very similar to the kqueue system calls, so you will need to have
135read and understood the kqueue man page. This document may seem fairly light on
136details but that is merely because the details are in the man page, and so I
137don't wish to replicate them here.
138
139=head1 API
140
141=head2 C<< IO::KQueue->new() >>
142
143Construct a new KQueue object (maps to the C<kqueue()> system call).
144
145=head2 C<< $kq->EV_SET($ident, $filt, $flags, $fflags, $data, $udata) >>
146
147e.g.:
148
149  $kq->EV_SET(fileno($server), EVFILT_READ, EV_ADD, 0, 5);
150
151Equivalent to the EV_SET macro followed immediately by a call to kevent() to
152set the event up.
153
154Note that to watch for both I<read> and I<write> events you need to call this
155method twice - once with EVFILT_READ and once with EVFILT_WRITE - unlike
156C<epoll()> and C<poll()> these "filters" are not a bitmask.
157
158Returns nothing. Throws an exception on failure.
159
160The C<$fflags>, C<$data> and C<$udata> params are optional.
161
162=head2 C<< $kq->kevent($timeout) >>
163
164Poll for events on the kqueue. Timeout is in milliseconds. If timeout is
165ommitted then we wait forever until there are events to read. If timeout is
166zero then we return immediately.
167
168Returns a list of arrayrefs which contain the kevent. The contents of the kevent
169are:
170
171=over 4
172
173=item * C<< $kevent->[KQ_IDENT] >>
174
175=item * C<< $kevent->[KQ_FILTER] >>
176
177=item * C<< $kevent->[KQ_FLAGS] >>
178
179=item * C<< $kevent->[KQ_FFLAGS] >>
180
181=item * C<< $kevent->[KQ_DATA] >>
182
183=item * C<< $kevent->[KQ_UDATA] >>
184
185See the included F<tail.pl> and F<chat.pl> scripts for example usage, and see
186the kqueue man pages for full details.
187
188=head1 CONSTANTS
189
190For a list of exported constants see the source of F<Makefile.PL>, or the
191kqueue man page. In addition the C<KQ_*> entries of the kevent are also
192exported - see the list above.
193
194=head1 LICENSE
195
196This is free software. You may use it and distribute it under the same terms
197as Perl itself - i.e. either the Perl Artistic License, or the GPL version 2.0.
198
199=head1 AUTHOR
200
201Matt Sergeant, <matt@sergeant.org>
202
203Copyright 2005 MessageLabs Ltd.
204
205=head1 SEE ALSO
206
207L<IO::Poll>
208
209=cut
210