select

        # Rake::FileList.select

(from ruby core)
### Implementation from Kernel
---
    IO.select(read_array [, write_array [, error_array [, timeout]]]) -> array or nil

---

Calls select(2) system call. It monitors given arrays of IO objects,
waits until one or more of IO objects are ready for reading, are ready
for writing, and have pending exceptions respectively, and returns an
array that contains arrays of those IO objects.  It will return `nil` if
optional *timeout* value is given and no IO object is ready in *timeout*
seconds.

IO.select peeks the buffer of IO objects for testing readability. If the
IO buffer is not empty, IO.select immediately notifies readability. 
This "peek" only happens for IO objects.  It does not happen for IO-like
objects such as OpenSSL::SSL::SSLSocket.

The best way to use IO.select is invoking it after nonblocking methods
such as #read_nonblock, #write_nonblock, etc.  The methods raise an
exception which is extended by IO::WaitReadable or IO::WaitWritable. 
The modules notify how the caller should wait with IO.select.  If
IO::WaitReadable is raised, the caller should wait for reading.  If
IO::WaitWritable is raised, the caller should wait for writing.

So, blocking read (#readpartial) can be emulated using #read_nonblock
and IO.select as follows:

    begin
      result = io_like.read_nonblock(maxlen)
    rescue IO::WaitReadable
      IO.select([io_like])
      retry
    rescue IO::WaitWritable
      IO.select(nil, [io_like])
      retry
    end

Especially, the combination of nonblocking methods and IO.select is
preferred for IO like objects such as OpenSSL::SSL::SSLSocket.  It has
#to_io method to return underlying IO object.  IO.select calls #to_io to
obtain the file descriptor to wait.

This means that readability notified by IO.select doesn't mean
readability from OpenSSL::SSL::SSLSocket object.

The most likely situation is that OpenSSL::SSL::SSLSocket buffers some
data.  IO.select doesn't see the buffer.  So IO.select can block when
OpenSSL::SSL::SSLSocket#readpartial doesn't block.

However, several more complicated situations exist.

SSL is a protocol which is sequence of records. The record consists of
multiple bytes. So, the remote side of SSL sends a partial record,
IO.select notifies readability but OpenSSL::SSL::SSLSocket cannot
decrypt a byte and OpenSSL::SSL::SSLSocket#readpartial will block.

Also, the remote side can request SSL renegotiation which forces the
local SSL engine to write some data. This means
OpenSSL::SSL::SSLSocket#readpartial may invoke #write system call and it
can block. In such a situation, OpenSSL::SSL::SSLSocket#read_nonblock
raises IO::WaitWritable instead of blocking. So, the caller should wait
for ready for writability as above example.

The combination of nonblocking methods and IO.select is also useful for
streams such as tty, pipe socket socket when multiple processes read
from a stream.

Finally, Linux kernel developers don't guarantee that readability of
select(2) means readability of following read(2) even for a single
process. See select(2) manual on GNU/Linux system.

Invoking IO.select before IO#readpartial works well as usual. However it
is not the best way to use IO.select.

The writability notified by select(2) doesn't show how many bytes are
writable. IO#write method blocks until given whole string is written.
So, `IO#write(two or more bytes)` can block after writability is
notified by IO.select.  IO#write_nonblock is required to avoid the
blocking.

Blocking write (#write) can be emulated using #write_nonblock and
IO.select as follows: IO::WaitReadable should also be rescued for SSL
renegotiation in OpenSSL::SSL::SSLSocket.

    while 0 < string.bytesize
      begin
        written = io_like.write_nonblock(string)
      rescue IO::WaitReadable
        IO.select([io_like])
        retry
      rescue IO::WaitWritable
        IO.select(nil, [io_like])
        retry
      end
      string = string.byteslice(written..-1)
    end

### Parameters
read_array
:   an array of IO objects that wait until ready for read
write_array
:   an array of IO objects that wait until ready for write
error_array
:   an array of IO objects that wait for exceptions
timeout
:   a numeric value in second


### Example

    rp, wp = IO.pipe
    mesg = "ping "
    100.times {
      # IO.select follows IO#read.  Not the best way to use IO.select.
      rs, ws, = IO.select([rp], [wp])
      if r = rs[0]
        ret = r.read(5)
        print ret
        case ret
        when /ping/
          mesg = "pong\n"
        when /pong/
          mesg = "ping "
        end
      end
      if w = ws[0]
        w.write(mesg)
      end
    }

*produces:*

    ping pong
    ping pong
    ping pong
    (snipped)
    ping