From: Gavin Sinclair <gsinclair@...>
Date: 2004-07-21T23:59:33+09:00
Subject: Re: sysread and buffered I/O

On Wednesday, July 21, 2004, 7:56:01 PM, Tanaka wrote:

> In article <189-1205065002.20040721185353@soyabean.com.au>,
>   Gavin Sinclair <gsinclair@soyabean.com.au> writes:

>> Tanaka, can you please give a brief description of the method (assume
>> I know nothing about advanced I/O), and I'll suggest a name.  Of
>> course, other people will too.

> [ruby-dev:23247] contains a patch including RDoc comment in English.

>  /*
>   *  call-seq:
>   *     ios.readpartial(integer [, buffer])    => string, buffer, or nil
>   *
>   *  Reads at most <i>integer</i> bytes from the I/O stream but
>   *  it blocks only if <em>ios</em> has no data immediately available.
>   *  If the optional <i>buffer</i> argument is present,
>   *  it must reference a String, which will receive the data.
>   *  It raises <code>EOFError</code> on end of file.
>   *     
>   *     STDIN.readpartial(4096)   #=> "Data immediately available"
>   */

> (The behavior on EOF is modified.)

What about this?

  1) read(n):
       current method; no problem if less than n bytes read,
       and no blocking

  2) read(n, :noeof):
       as (1), but raises EOFError on end of file

  3) read(n, :noeof, :pblock):
       as (2), but *partially* blocks; i.e. blocks only if no data
       is immediately available

  4) read(n, :exact):
       as (1), raise some error if less than n bytes read
       (implies :noeof)

  5) read(n, :exact, :block):
       as (4), but block until n bytes are available

  6) read(n, :exact, :pblock):
       as (4), but *partially* block, as per (3)

All methods can accept a String parameter which acts as the receiving
buffer.  The 'n' parameter must come first; the order of the rest
doesn't matter.

The naming of "pblock" could definitely be better...

Gavin