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 warnings::register;
11 use vars qw($VERSION @ISA);
16 @ISA = qw(Exporter); # This is only so we can do version checking
25 my $type = ref($self) || $self;
27 my $vec = bless [undef,0], $type;
37 shift->_update('add', @_);
43 shift->_update('remove', @_);
50 my $fno = $vec->_fileno(shift);
51 return undef unless defined $fno;
52 $vec->[$fno + FIRST_FD];
59 $f = $f->[0] if ref($f) eq 'ARRAY';
60 ($f =~ /^\d+$/) ? $f : fileno($f);
66 my $add = shift eq 'add';
68 my $bits = $vec->[VEC_BITS];
69 $bits = '' unless defined $bits;
75 my $fn = $vec->_fileno($f);
76 next unless defined $fn;
77 my $i = $fn + FIRST_FD;
79 if (defined $vec->[$i]) {
80 $vec->[$i] = $f; # if array rest might be different, so we update
84 vec($bits, $fn, 1) = 1;
87 next unless defined $vec->[$i];
89 vec($bits, $fn, 1) = 0;
94 $vec->[VEC_BITS] = $vec->[FD_COUNT] ? $bits : undef;
102 my $r = $vec->[VEC_BITS];
104 defined($r) && (select($r,undef,undef,$timeout) > 0)
113 my $w = $vec->[VEC_BITS];
115 defined($w) && (select(undef,$w,undef,$timeout) > 0)
124 my $e = $vec->[VEC_BITS];
126 defined($e) && (select(undef,undef,$e,$timeout) > 0)
133 warnings::warn("Call to depreciated method 'has_error', use 'has_exception'")
134 if warnings::enabled();
150 sub as_string # for debugging
153 my $str = ref($vec) . ": ";
154 my $bits = $vec->bits;
155 my $count = $vec->count;
156 $str .= defined($bits) ? unpack("b*", $bits) : "undef";
159 splice(@handles, 0, FIRST_FD);
161 $str .= " " . (defined($_) ? "$_" : "-");
181 if defined $_[0] && !ref($_[0]);
183 my($r,$w,$e,$t) = @_;
186 my $rb = defined $r ? $r->[VEC_BITS] : undef;
187 my $wb = defined $w ? $w->[VEC_BITS] : undef;
188 my $eb = defined $e ? $e->[VEC_BITS] : undef;
190 if(select($rb,$wb,$eb,$t) > 0)
195 my $i = _max(defined $r ? scalar(@$r)-1 : 0,
196 defined $w ? scalar(@$w)-1 : 0,
197 defined $e ? scalar(@$e)-1 : 0);
199 for( ; $i >= FIRST_FD ; $i--)
201 my $j = $i - FIRST_FD;
203 if defined $rb && defined $r->[$i] && vec($rb, $j, 1);
205 if defined $wb && defined $w->[$i] && vec($wb, $j, 1);
207 if defined $eb && defined $e->[$i] && vec($eb, $j, 1);
210 @result = (\@r, \@w, \@e);
222 my $max = scalar(@$vec) - 1;
224 for ($i = FIRST_FD; $i <= $max; $i++)
226 next unless defined $vec->[$i];
228 if !defined($bits) || vec($bits, $i - FIRST_FD, 1);
239 IO::Select - OO interface to the select system call
245 $s = IO::Select->new();
248 $s->add($some_handle);
250 @ready = $s->can_read($timeout);
252 @ready = IO::Select->new(@handles)->read(0);
256 The C<IO::Select> package implements an object approach to the system C<select>
257 function call. It allows the user to see what IO handles, see L<IO::Handle>,
258 are ready for reading, writing or have an error condition pending.
264 =item new ( [ HANDLES ] )
266 The constructor creates a new object and optionally initialises it with a set
275 =item add ( HANDLES )
277 Add the list of handles to the C<IO::Select> object. It is these values that
278 will be returned when an event occurs. C<IO::Select> keeps these values in a
279 cache which is indexed by the C<fileno> of the handle, so if more than one
280 handle with the same C<fileno> is specified then only the last one is cached.
282 Each handle can be an C<IO::Handle> object, an integer or an array
283 reference where the first element is a C<IO::Handle> or an integer.
285 =item remove ( HANDLES )
287 Remove all the given handles from the object. This method also works
288 by the C<fileno> of the handles. So the exact handles that were added
289 need not be passed, just handles that have an equivalent C<fileno>
291 =item exists ( HANDLE )
293 Returns a true value (actually the handle itself) if it is present.
294 Returns undef otherwise.
298 Return an array of all registered handles.
300 =item can_read ( [ TIMEOUT ] )
302 Return an array of handles that are ready for reading. C<TIMEOUT> is
303 the maximum amount of time to wait before returning an empty list. If
304 C<TIMEOUT> is not given and any handles are registered then the call
307 =item can_write ( [ TIMEOUT ] )
309 Same as C<can_read> except check for handles that can be written to.
311 =item has_exception ( [ TIMEOUT ] )
313 Same as C<can_read> except check for handles that have an exception
314 condition, for example pending out-of-band data.
318 Returns the number of handles that the object will check for when
319 one of the C<can_> methods is called or the object is passed to
320 the C<select> static method.
324 Return the bit string suitable as argument to the core select() call.
326 =item select ( READ, WRITE, ERROR [, TIMEOUT ] )
328 C<select> is a static method, that is you call it with the package
329 name like C<new>. C<READ>, C<WRITE> and C<ERROR> are either C<undef>
330 or C<IO::Select> objects. C<TIMEOUT> is optional and has the same
331 effect as for the core select call.
333 The result will be an array of 3 elements, each a reference to an array
334 which will hold the handles that are ready for reading, writing and have
335 error conditions respectively. Upon error an empty array is returned.
341 Here is a short example which shows how C<IO::Select> could be used
342 to write a server which communicates with several sockets while also
343 listening for more connections on a listen socket
348 $lsn = new IO::Socket::INET(Listen => 1, LocalPort => 8080);
349 $sel = new IO::Select( $lsn );
351 while(@ready = $sel->can_read) {
352 foreach $fh (@ready) {
354 # Create a new socket
361 # Maybe we have finished with the socket
370 Graham Barr. Currently maintained by the Perl Porters. Please report all
371 bugs to <perl5-porters@perl.org>.
375 Copyright (c) 1997-8 Graham Barr <gbarr@pobox.com>. All rights reserved.
376 This program is free software; you can redistribute it and/or
377 modify it under the same terms as Perl itself.