[m-rev.] for review: add unboxed_readers to the stream module

[Julien Fischer]

Hi Peter,

On Sun, 19 Apr 2020, Peter Wang wrote:

> On Sat, 18 Apr 2020 15:34:40 +1000 (AEST), Julien Fischer <jfischer at opturion.com> wrote:
>>
>> For review by anyone.
>>
>> ------------------------
>>
>> Add unboxed_readers to the stream module.
>>
>> library/stream.m:
>>      Add a new type of reader, unboxed_reader.  These provide a 'get'
>>      operation that does not need to box its output in the non-error case.
>>
>> library/io.m:
>>      Add an unboxed_reader instance for text_input_streams and chars.
>>
>> NEWS:
>>     Announce the addition.

...

>
>> @@ -122,6 +123,30 @@
>>           State::di, State::uo) is det
>>   ].
>>
>> +    % An unboxed_reader stream is like a reader stream except that it provides
>> +    % an interface that avoids a memory allocation when there is no error.
>> +    %
>> +:- typeclass unboxed_reader(Stream, Unit, State, Error)
>> +    <= (input(Stream, State), error(Error), (Stream, Unit -> Error)) where
>> +[
>> +    % Get the next unit from the given stream.
>> +    %
>> +    % The unboxed_get operation should block until the next unit is available,
>> +    % or the end of the stream or an error is detected.
>> +    %
>> +    % If a call to unboxed_get/5 returns `eof', all further calls to get/4,
>> +    % unboxed_get/5 or bulk_get/9 for that stream return `eof'. If a call to
>> +    % unboxed_get/5 returns `error(...)', all further calls to get/4,
>> +    % unboxed_get/5 or bulk_get/4 for that stream return an error, although not
>> +    % necessarily the same one.
>> +    %
>> +    % XXX We should provide an interface to allow the user to reset the
>> +    % error status to try again if an error is transient.
>> +    %
>> +    pred unboxed_get(Stream::in, result(Error)::out, Unit::out,
>> +        State::di, State::uo) is det
>> +].
>> +
>
> It should say something about the return value in case of eof or error,
> i.e. no particular value is guaranteed. io.read_char_unboxed also lacks
> that documentation, oops.

Ok, I've added the following to it:

     % Get the next unit from the given stream. On error or eof an
     % arbitrary value of type Unit is returned.

I don't think the type class interface can, or should, make stronger
guarantees than that; obviously for read_char_unboxed we can document
that it returns 0.

I'm planning to add predicates to the io module that read uint8s / int8s
from binary input streams without boxing the results; I'll fix up the
documentation for read_char_unboxed at that point.

> I prefer the name io.read_char_unboxed over io.unboxed_read_char as it
> is a minor variation on io.read_char, and keeps the important part (the
> operation) up front. Therefore, I suggest to name the new method
> get_unboxed, but it's only a slight suggestion.

We already have type class named bulk_reader which has the method
bulk_get, so for the sake of consistency (at least amongst the
stream type classes themselves), I'd prefer to keep the names
as I had them.

> reader_unboxed for the typeclass name does read awkwardly, though.

It does, that's why I didn't use it ;-)

Julien.