mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-05-20 11:40:18 +02:00
Code Activity

Update port implementation documentation.

Browse source 
* doc/ref/api-io.texi (I/O Extensions): Update read/write
  documentation.
This commit is contained in:
Andy Wingo 2016-04-12 16:31:20 +02:00
parent f7027a8b88
commit d83140890f
1 changed files with 12 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

20
doc/ref/api-io.texi
View file

@ -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{buf} field. The valid data in the buffer is between the
@code{cur} and @code{end} indices into @code{buf}; @code{cur} must @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 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
@code{bytevector} 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 ``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 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}. A port type object is created by calling @code{scm_make_port_type}.
@deftypefun 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)) @deftypefun 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 Return a new port type object. The @var{name}, @var{read} and
@var{write} parameters are initial values for those port type fields, as @var{write} parameters are initial values for those port type fields, as
described below. The other fields are initialized with default values 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 @item read
A port's @code{read} implementation fills read buffers. It should copy A port's @code{read} implementation fills read buffers. It should copy
bytes to the supplied port buffer object, advancing the buffer's bytes to the supplied bytevector @code{dst}, starting at offset
@code{end} field as appropriate, but not past the buffer's @code{size} @code{start} and continuing for @code{count} bytes, returning the number
field. of bytes read.
@item write @item write
A port's @code{write} implementation flushes write buffers to the A port's @code{write} implementation flushes write buffers to the
mutable store. It should copy bytes from the supplied port buffer mutable store. A port's @code{read} implementation fills read buffers.
object, advancing the buffer's @code{cur} field as appropriate, but not It should write out bytes from the supplied bytevector @code{src},
past the buffer's @code{end} field. starting at offset @code{start} and continuing for @code{count} bytes,
and return the number of bytes that were written.
@item print @item print
Called when @code{write} is called on the port object, to print a Called when @code{write} is called on the port object, to print a