=head1 NAME

IO::Mux::Select - simplify use of select()

=head1 INHERITANCE

 IO::Mux::Select
   is a IO::Mux

=head1 SYNOPSIS

  use IO::Mux::Select;

  my $mux    = IO::Mux::Select->new;
  my $server = IO::Mux::Service::TCP->new(...);
  $mux->add($server);
  $mux->loop;

=head1 DESCRIPTION

Multiplexer implemented around the C<select()> system call. This C<select()>
is usually less powerful and slower than the C<poll()> call (implemented
in L<IO::Mux::Poll|IO::Mux::Poll>) however probably available on more systems.

=head1 METHODS

=head2 Constructors

=over 4

=item IO::Mux::Select-E<gt>B<new>(OPTIONS)
See L<IO::Mux/"Constructors">

=back

=head2 Accessors

=head2 User interface

=over 4

=item $obj-E<gt>B<add>(HANDLER|BUNDLE)
See L<IO::Mux/"User interface">

=item $obj-E<gt>B<endLoop>(BOOLEAN)
See L<IO::Mux/"User interface">

=item $obj-E<gt>B<loop>([HEARTBEAT])
See L<IO::Mux/"User interface">

=item $obj-E<gt>B<open>(MODE, PARAMS)
See L<IO::Mux/"User interface">

=item $obj-E<gt>B<showFlags>([FLAGS|(RDFLAGS,WRFLAGS,EXFLAGS)])

Display the select FLAGS (one of the values received from L<selectFlags()|IO::Mux::Select/"For internal use">)
or all of these flags. You may also specify three sets of FLAGS explicitly.

When three sets of FLAGS are passed, it will result in three lines
preceeded with labels. With only one set, no label will be used.

The flagged filenos are shown numerically (modulo 10) and positionally.
For instance, if both filehandle 1 and 4 are flagged, the output string
will be C<-1--4>.

example: 

  my ($rd, $wr, $er) = $client->selectFlags;
  print "read flags: ",$client->showFlags($rd);

  print $client->showFlags(rd, $wr, $er);
  print $client->showFlags;   # saem result

  print $client->showFlags($client->waitFlags);

=back

=head2 For internal use

=over 4

=item $obj-E<gt>B<changeTimeout>(FILENO, OLDTIMEOUT, NEWTIMEOUT)
See L<IO::Mux/"For internal use">

=item $obj-E<gt>B<fdset>(FILENO, STATE, READ, WRITE, EXCEPT)
See L<IO::Mux/"For internal use">

=item $obj-E<gt>B<handler>(FILENO, [HANDLER])
See L<IO::Mux/"For internal use">

=item $obj-E<gt>B<handlers>
See L<IO::Mux/"For internal use">

=item $obj-E<gt>B<remove>(FILENO)
See L<IO::Mux/"For internal use">

=item $obj-E<gt>B<selectFlags>

Returns a list of three: respectively the read, write and error flags
which show the file numbers that the internal C<select()> call has
flagged as needing inspection.

This method can, for instance, be used from within the heartbeat routine.

example: 

  $mux->loop(\&heartbeat);
  sub heartbeat($$$)
  {   my ($mux, $numready, $timeleft) = @_;
      my ($rd, $rw, $ex) = $mux->selectFlags;
      if(vec($rd, $fileno, 1)==1) {...}
  }

=item $obj-E<gt>B<waitFlags>

Returns a list of three: respectively the read, write and error flags
which show how the files are enlisted.

=back

=head1 DETAILS

=head2 Installation

=head2 Event managers

=head2 File handles

=head2 Alternatives

=head3 IO::Multiplex

=head4 Difference to IO::Multiplex

=head3 IO::Async / Net::Async

=head2 Implementation limitations

=head3 Limitations on Windows

The C<select()> system call is very limited: it only works on sockets,
not on files or pipes. This means that the process will stall on each
file access and pipe activity.

=head3 Limitations on UNIX/Linux

Be careful with the use of files. You should open files with the
non-stdio version of C<open()>, with option C<O_NONBLOCK>. But even
then, asynchronous support for reading and writing files and pipes
may be lacking on your UNIX dialect.

=back

The C<select> system call is very powerful, however the (UNIX) standard
specifies quite a weak subset of the features usually offered. The
standard only requires sockets to be supported. The Windows/cygwin
implementation limits itself to that. Modern UNIX dialects usually
also support normal pipes and file handlers to be attached.

Please help extending the list of OS specific limitations below!

=head1 SEE ALSO

This module is part of IO-Mux distribution version 0.11,
built on January 26, 2011. Website: F<http://perl.overmeer.net/>
All modules in this suite:
L</Any::Daemon>,
L</IO::Mux>, and
L</IO::Mux::HTTP>.

Please post questions or ideas to F<perl@overmeer.net>

=head1 LICENSE

Copyrights 2011 by Mark Overmeer. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>

