[m-rev.] for review: Make io.m not throw exceptions across the C interface; other fixes.

[Julien Fischer]

Hi Peter,

On Thu, 22 Sep 2016, Peter Wang wrote:

> io.m would throw exceptions on error by calling foreign_exported Mercury
> procedures from foreign code, but this is not supported in low-level
> C grades where the C stack would not be unwound when the exception
> is thrown.
>
> A better style, arguably, is to return error codes from foreign code
> back up to Mercury code, then throw exceptions from the Mercury code.
> For consistency, all the backends now operate in this way.
>
> library/io.m:
>    Change documentation of `putback_char' and `putback_byte' not to
>    refer to the C library.
>
>    Add documentation for the internal `system_error' type. We will use
>    reserved values of system_error (0, null, ok) to report success.
>
>    Delete unused predicate `output_stream_file_size'.
>
>    Delete obsolete C functions `mercury_io_error',
>    `mercury_output_error', `mercury_print_string'.
>
>    Make C function `mercury_close' return an error indicator instead
>    of throwing an exception directly on error.
>
>    Delete obsolete Java methods `put_or_throw', `write_or_throw', etc.
>
>    Delete Java method `throw_io_error'. Replace uses indicating
>    unreachable code with `throw new RuntimeException'.
>
>    Fix a bug with Java `putback_byte': the popped byte would be returned
>    as signed [-128, 127] instead of unsigned [0, 255].
>
>    Make Erlang `close', `sync' implementations return error to caller.
>
>    Fix Erlang `get_file_size' implementation to send the correct
>    acknowledgement message.
>
>    Add helper predicates `throw_on_error', `throw_on_output_error',
>    `throw_on_close_error', `is_error'.
>
>    Delete the foreign-code implementations of implicit-stream predicates,
>    replacing them with simple Mercury predicates that call the
>    explicit-stream predicates. This saves a lot of almost duplicate code.
>
>    Make I/O predicates return error codes from the inner foreign_procs
>    back up to Mercury code. On error, throw exceptions from the
>    Mercury code.
>
>    Check for zero and negative NumBytes to `write_bitmap'.
>
>    Replace generic implementation of `do_write_bitmap' with efficient
>    implementations for Java, C# and Erlang.
>
>    Check for errors in C implementations of `seek_binary_2'
>    and `binary_stream_offset_2'.
>
>    Check for error in Erlang implementations `seek_binary_2',
>    `binary_stream_offset_2', `flush_output_2', `flush_binary_output_2'.
>
>    Add comments indicating changes yet to be made.

One comment: you've changed the status of many foreign_procs from
"may_call_mercury" -> "will_not_call_mercury".   You can delete the
"terminates" attribute from those foreign_procs, since that is implied
by "will_not_call_mercury".

The rest looks ok.

Julien.