[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Guile-commits] 01/06: Update port implementation documentation.
From: |
Andy Wingo |
Subject: |
[Guile-commits] 01/06: Update port implementation documentation. |
Date: |
Thu, 14 Apr 2016 14:34:12 +0000 |
wingo pushed a commit to branch wip-port-refactor
in repository guile.
commit d83140890fa112737a895feeaa5e90a952fedce7
Author: Andy Wingo <address@hidden>
Date: Tue Apr 12 16:31:20 2016 +0200
Update port implementation documentation.
* doc/ref/api-io.texi (I/O Extensions): Update read/write
documentation.
---
doc/ref/api-io.texi | 20 ++++++++++++--------
1 files changed, 12 insertions(+), 8 deletions(-)
diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index b5e70cf..78f7cae 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -2289,7 +2289,10 @@ The port buffer consists of data as a byte array,
pointed to by its
@code{buf} field. The valid data in the buffer is between the
@code{cur} and @code{end} indices into @code{buf}; @code{cur} must
always be less than or equal to @code{end}, which in turn must be less
-than or equal to the buffer size @code{size}.
+than or equal to the buffer size @code{size}. The @code{buf} pointer is
+actually a pointer to the start of a bytevector, stored in the
address@hidden member. Using bytevectors to back port buffers allows
+Scheme to manipulate these buffers.
``Valid data'' for a read buffer is data that has been buffered, but not
yet read by the user. A port's @code{read} procedure fills a read
@@ -2330,7 +2333,7 @@ implementation.
A port type object is created by calling @code{scm_make_port_type}.
address@hidden scm_t_bits scm_make_port_type (char *name, void (*read) (SCM
port, scm_t_port_buffer *dst), void (*write) (SCM port, scm_t_port_buffer *src))
address@hidden scm_t_bits scm_make_port_type (char *name, size_t (*read) (SCM
port, SCM dst, size_t start, size_t count), size_t (*write) (SCM port, SCM src,
size_t start, size_t count))
Return a new port type object. The @var{name}, @var{read} and
@var{write} parameters are initial values for those port type fields, as
described below. The other fields are initialized with default values
@@ -2349,15 +2352,16 @@ a procedure. Set via the first argument to
@code{scm_make_port_type}.
@item read
A port's @code{read} implementation fills read buffers. It should copy
-bytes to the supplied port buffer object, advancing the buffer's
address@hidden field as appropriate, but not past the buffer's @code{size}
-field.
+bytes to the supplied bytevector @code{dst}, starting at offset
address@hidden and continuing for @code{count} bytes, returning the number
+of bytes read.
@item write
A port's @code{write} implementation flushes write buffers to the
-mutable store. It should copy bytes from the supplied port buffer
-object, advancing the buffer's @code{cur} field as appropriate, but not
-past the buffer's @code{end} field.
+mutable store. A port's @code{read} implementation fills read buffers.
+It should write out bytes from the supplied bytevector @code{src},
+starting at offset @code{start} and continuing for @code{count} bytes,
+and return the number of bytes that were written.
@item print
Called when @code{write} is called on the port object, to print a
- [Guile-commits] branch wip-port-refactor updated (f7027a8 -> 25461be), Andy Wingo, 2016/04/14
- [Guile-commits] 03/06: Fix error in exception printer when bootstrapping, Andy Wingo, 2016/04/14
- [Guile-commits] 05/06: Fix R6RS imports of interfaces that use interfaces, Andy Wingo, 2016/04/14
- [Guile-commits] 02/06: Allow port "write" functions to only write a chunk, Andy Wingo, 2016/04/14
- [Guile-commits] 01/06: Update port implementation documentation.,
Andy Wingo <=
- [Guile-commits] 04/06: Fix scm_init_struct dependency on port conversion handlers, Andy Wingo, 2016/04/14
- [Guile-commits] 06/06: Load port bindings in separate (ice-9 ports) module, Andy Wingo, 2016/04/14