io.rb

   1 class IO
   2   # other IO methods are defined in io.c
   3
   4   # call-seq:
   5   #    ios.read_nonblock(maxlen [, options])              -> string
   6   #    ios.read_nonblock(maxlen, outbuf [, options])      -> outbuf
   7   #
   8   # Reads at most <i>maxlen</i> bytes from <em>ios</em> using
   9   # the read(2) system call after O_NONBLOCK is set for
  10   # the underlying file descriptor.
  11   #
  12   # If the optional <i>outbuf</i> argument is present,
  13   # it must reference a String, which will receive the data.
  14   # The <i>outbuf</i> will contain only the received data after the method call
  15   # even if it is not empty at the beginning.
  16   #
  17   # read_nonblock just calls the read(2) system call.
  18   # It causes all errors the read(2) system call causes: Errno::EWOULDBLOCK, Errno::EINTR, etc.
  19   # The caller should care such errors.
  20   #
  21   # If the exception is Errno::EWOULDBLOCK or Errno::EAGAIN,
  22   # it is extended by IO::WaitReadable.
  23   # So IO::WaitReadable can be used to rescue the exceptions for retrying
  24   # read_nonblock.
  25   #
  26   # read_nonblock causes EOFError on EOF.
  27   #
  28   # On some platforms, such as Windows, non-blocking mode is not supported
  29   # on IO objects other than sockets. In such cases, Errno::EBADF will
  30   # be raised.
  31   #
  32   # If the read byte buffer is not empty,
  33   # read_nonblock reads from the buffer like readpartial.
  34   # In this case, the read(2) system call is not called.
  35   #
  36   # When read_nonblock raises an exception kind of IO::WaitReadable,
  37   # read_nonblock should not be called
  38   # until io is readable for avoiding busy loop.
  39   # This can be done as follows.
  40   #
  41   #   # emulates blocking read (readpartial).
  42   #   begin
  43   #     result = io.read_nonblock(maxlen)
  44   #   rescue IO::WaitReadable
  45   #     IO.select([io])
  46   #     retry
  47   #   end
  48   #
  49   # Although IO#read_nonblock doesn't raise IO::WaitWritable.
  50   # OpenSSL::Buffering#read_nonblock can raise IO::WaitWritable.
  51   # If IO and SSL should be used polymorphically,
  52   # IO::WaitWritable should be rescued too.
  53   # See the document of OpenSSL::Buffering#read_nonblock for sample code.
  54   #
  55   # Note that this method is identical to readpartial
  56   # except the non-blocking flag is set.
  57   #
  58   # By specifying a keyword argument _exception_ to +false+, you can indicate
  59   # that read_nonblock should not raise an IO::WaitReadable exception, but
  60   # return the symbol +:wait_readable+ instead. At EOF, it will return nil
  61   # instead of raising EOFError.
  62   def read_nonblock(len, buf = nil, exception: true)
  63     Primitive.io_read_nonblock(len, buf, exception)
  64   end
  65
  66   # call-seq:
  67   #    ios.write_nonblock(string)   -> integer
  68   #    ios.write_nonblock(string [, options])   -> integer
  69   #
  70   # Writes the given string to <em>ios</em> using
  71   # the write(2) system call after O_NONBLOCK is set for
  72   # the underlying file descriptor.
  73   #
  74   # It returns the number of bytes written.
  75   #
  76   # write_nonblock just calls the write(2) system call.
  77   # It causes all errors the write(2) system call causes: Errno::EWOULDBLOCK, Errno::EINTR, etc.
  78   # The result may also be smaller than string.length (partial write).
  79   # The caller should care such errors and partial write.
  80   #
  81   # If the exception is Errno::EWOULDBLOCK or Errno::EAGAIN,
  82   # it is extended by IO::WaitWritable.
  83   # So IO::WaitWritable can be used to rescue the exceptions for retrying write_nonblock.
  84   #
  85   #   # Creates a pipe.
  86   #   r, w = IO.pipe
  87   #
  88   #   # write_nonblock writes only 65536 bytes and return 65536.
  89   #   # (The pipe size is 65536 bytes on this environment.)
  90   #   s = "a" * 100000
  91   #   p w.write_nonblock(s)     #=> 65536
  92   #
  93   #   # write_nonblock cannot write a byte and raise EWOULDBLOCK (EAGAIN).
  94   #   p w.write_nonblock("b")   # Resource temporarily unavailable (Errno::EAGAIN)
  95   #
  96   # If the write buffer is not empty, it is flushed at first.
  97   #
  98   # When write_nonblock raises an exception kind of IO::WaitWritable,
  99   # write_nonblock should not be called
 100   # until io is writable for avoiding busy loop.
 101   # This can be done as follows.
 102   #
 103   #   begin
 104   #     result = io.write_nonblock(string)
 105   #   rescue IO::WaitWritable, Errno::EINTR
 106   #     IO.select(nil, [io])
 107   #     retry
 108   #   end
 109   #
 110   # Note that this doesn't guarantee to write all data in string.
 111   # The length written is reported as result and it should be checked later.
 112   #
 113   # On some platforms such as Windows, write_nonblock is not supported
 114   # according to the kind of the IO object.
 115   # In such cases, write_nonblock raises <code>Errno::EBADF</code>.
 116   #
 117   # By specifying a keyword argument _exception_ to +false+, you can indicate
 118   # that write_nonblock should not raise an IO::WaitWritable exception, but
 119   # return the symbol +:wait_writable+ instead.
 120   def write_nonblock(buf, exception: true)
 121     Primitive.io_write_nonblock(buf, exception)
 122   end
 123 end