3 # Copyright (c) 1997-8 Graham Barr <gbarr@pobox.com>. All rights reserved.
4 # This program is free software; you can redistribute it and/or
5 # modify it under the same terms as Perl itself.
10 use vars qw($VERSION @ISA);
15 @ISA = qw(Exporter); # This is only so we can do version checking
24 my $type = ref($self) || $self;
26 my $vec = bless [undef,0], $type;
36 shift->_update('add', @_);
42 shift->_update('remove', @_);
49 $vec->[$vec->_fileno(shift) + FIRST_FD];
56 $f = $f->[0] if ref($f) eq 'ARRAY';
57 ($f =~ /^\d+$/) ? $f : fileno($f);
63 my $add = shift eq 'add';
65 my $bits = $vec->[VEC_BITS];
66 $bits = '' unless defined $bits;
72 my $fn = $vec->_fileno($f);
73 next unless defined $fn;
74 my $i = $fn + FIRST_FD;
76 if (defined $vec->[$i]) {
77 $vec->[$i] = $f; # if array rest might be different, so we update
81 vec($bits, $fn, 1) = 1;
84 next unless defined $vec->[$i];
86 vec($bits, $fn, 1) = 0;
91 $vec->[VEC_BITS] = $vec->[FD_COUNT] ? $bits : undef;
99 my $r = $vec->[VEC_BITS];
101 defined($r) && (select($r,undef,undef,$timeout) > 0)
110 my $w = $vec->[VEC_BITS];
112 defined($w) && (select(undef,$w,undef,$timeout) > 0)
121 my $e = $vec->[VEC_BITS];
123 defined($e) && (select(undef,undef,$e,$timeout) > 0)
131 Carp::carp("Call to depreciated method 'has_error', use 'has_exception'")
148 sub as_string # for debugging
151 my $str = ref($vec) . ": ";
152 my $bits = $vec->bits;
153 my $count = $vec->count;
154 $str .= defined($bits) ? unpack("b*", $bits) : "undef";
157 splice(@handles, 0, FIRST_FD);
159 $str .= " " . (defined($_) ? "$_" : "-");
179 if defined $_[0] && !ref($_[0]);
181 my($r,$w,$e,$t) = @_;
184 my $rb = defined $r ? $r->[VEC_BITS] : undef;
185 my $wb = defined $w ? $w->[VEC_BITS] : undef;
186 my $eb = defined $e ? $e->[VEC_BITS] : undef;
188 if(select($rb,$wb,$eb,$t) > 0)
193 my $i = _max(defined $r ? scalar(@$r)-1 : 0,
194 defined $w ? scalar(@$w)-1 : 0,
195 defined $e ? scalar(@$e)-1 : 0);
197 for( ; $i >= FIRST_FD ; $i--)
199 my $j = $i - FIRST_FD;
201 if defined $rb && defined $r->[$i] && vec($rb, $j, 1);
203 if defined $wb && defined $w->[$i] && vec($wb, $j, 1);
205 if defined $eb && defined $e->[$i] && vec($eb, $j, 1);
208 @result = (\@r, \@w, \@e);
220 my $max = scalar(@$vec) - 1;
222 for ($i = FIRST_FD; $i <= $max; $i++)
224 next unless defined $vec->[$i];
226 if !defined($bits) || vec($bits, $i - FIRST_FD, 1);
237 IO::Select - OO interface to the select system call
243 $s = IO::Select->new();
246 $s->add($some_handle);
248 @ready = $s->can_read($timeout);
250 @ready = IO::Select->new(@handles)->read(0);
254 The C<IO::Select> package implements an object approach to the system C<select>
255 function call. It allows the user to see what IO handles, see L<IO::Handle>,
256 are ready for reading, writing or have an error condition pending.
262 =item new ( [ HANDLES ] )
264 The constructor creates a new object and optionally initialises it with a set
273 =item add ( HANDLES )
275 Add the list of handles to the C<IO::Select> object. It is these values that
276 will be returned when an event occurs. C<IO::Select> keeps these values in a
277 cache which is indexed by the C<fileno> of the handle, so if more than one
278 handle with the same C<fileno> is specified then only the last one is cached.
280 Each handle can be an C<IO::Handle> object, an integer or an array
281 reference where the first element is a C<IO::Handle> or an integer.
283 =item remove ( HANDLES )
285 Remove all the given handles from the object. This method also works
286 by the C<fileno> of the handles. So the exact handles that were added
287 need not be passed, just handles that have an equivalent C<fileno>
289 =item exists ( HANDLE )
291 Returns a true value (actually the handle itself) if it is present.
292 Returns undef otherwise.
296 Return an array of all registered handles.
298 =item can_read ( [ TIMEOUT ] )
300 Return an array of handles that are ready for reading. C<TIMEOUT> is
301 the maximum amount of time to wait before returning an empty list. If
302 C<TIMEOUT> is not given and any handles are registered then the call
305 =item can_write ( [ TIMEOUT ] )
307 Same as C<can_read> except check for handles that can be written to.
309 =item has_exception ( [ TIMEOUT ] )
311 Same as C<can_read> except check for handles that have an exception
312 condition, for example pending out-of-band data.
316 Returns the number of handles that the object will check for when
317 one of the C<can_> methods is called or the object is passed to
318 the C<select> static method.
322 Return the bit string suitable as argument to the core select() call.
324 =item select ( READ, WRITE, ERROR [, TIMEOUT ] )
326 C<select> is a static method, that is you call it with the package
327 name like C<new>. C<READ>, C<WRITE> and C<ERROR> are either C<undef>
328 or C<IO::Select> objects. C<TIMEOUT> is optional and has the same
329 effect as for the core select call.
331 The result will be an array of 3 elements, each a reference to an array
332 which will hold the handles that are ready for reading, writing and have
333 error conditions respectively. Upon error an empty array is returned.
339 Here is a short example which shows how C<IO::Select> could be used
340 to write a server which communicates with several sockets while also
341 listening for more connections on a listen socket
346 $lsn = new IO::Socket::INET(Listen => 1, LocalPort => 8080);
347 $sel = new IO::Select( $lsn );
349 while(@ready = $sel->can_read) {
350 foreach $fh (@ready) {
352 # Create a new socket
359 # Maybe we have finished with the socket
368 Graham Barr. Currently maintained by the Perl Porters. Please report all
369 bugs to <perl5-porters@perl.org>.
373 Copyright (c) 1997-8 Graham Barr <gbarr@pobox.com>. All rights reserved.
374 This program is free software; you can redistribute it and/or
375 modify it under the same terms as Perl itself.