streams: put_buf and fill_buf become lower-level.

In this commit, the put_buf and fill_buf stream virtual
functions are changed to operate directly on a low-level
buffer, rather than a stream. This will allow these functions
to be used for improving the performance of I/O operations
that are not related to buffer objects.

* stream.h (struct strm_ops): Change type signature of put_buf
and fill_buf members. The lengths and iszes are ucnum.
The return value is ucnum. The buffer is passed as a pointer
and length, rather than a buffer object.

* stream.c (unimpl_put_buf, unimpl_fill_buf, generic_put_buf,
generic_fill_buf, stdio_put_buf, stdio_fill_buf,
delegate_put_buf, delegate_fill_buf): Adjust to
new interface.
(put_buf, fill_buf, fill_buf_adjust): Pull the poitner and
size from the buffer and pass those down to the virtual
functions rather than the buffer itself. Convert ucnum return
value to val.

* strudel.c (strudel_put_buf, strudel_get_buf): The struct
delegate interface doesn't change. The put-buf and fill-buf
methods still operate on buffer objects. To glue that with the
new low-level interface, we  use the init_borrowed_buf trick
that is was first used in ffi.c: temporary buf objects are
efficiently allocated on the stack, pointing to the same
memory that is coming down from the stream operation.

* txr.1: Document the new restrictions on the buf argument of
the put-buf and fill-buf stream delegate methods.
Since the buf not a heap object, it cannot be used after the
method returns.

1 files changed, 24 insertions, 0 deletions

diff --git a/txr.1 b/txr.1
index ea70cf2f..5b77a5f5 100644
--- a/txr.1
+++ b/txr.1
@@ -52509,6 +52509,18 @@ description of the
 .code put-buf
 stream I/O function.
 
+Note: there is a severe restriction on the use of the
+.meta buf
+argument. The buffer object denoted by the
+.meta buf
+argument may be specially allocated and have a lifetime
+which is scoped to the method invocation. The
+.code put-buf
+method shall not permit the
+.meta buf
+object to be used beyond the duration of the method
+invocaton.
+
 .coNP Method @ fill-buf
 .synb
 .mets << stream .(fill-buf buf pos)
@@ -52522,6 +52534,18 @@ description of the
 .code fill-buf
 stream I/O function.
 
+Note: there is a severe restriction on the use of the
+.meta buf
+argument. The buffer object denoted by the
+.meta buf
+argument may be specially allocted and have a lifetime
+which is scoped to the method invocation. The
+.code put-buf
+method shall not permit the
+.meta buf
+object to be used beyond the duration of the method
+invocaton.
+
 .coNP Method @ close
 .synb
 .mets << stream .(close offs whence)