[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Guile-commits] 15/21: Update port type documentation
From: |
Andy Wingo |
Subject: |
[Guile-commits] 15/21: Update port type documentation |
Date: |
Mon, 16 May 2016 07:39:35 +0000 (UTC) |
wingo pushed a commit to branch wip-port-refactor
in repository guile.
commit 9322902d02ecc23ec4c8534dbbc03c3074b78217
Author: Andy Wingo <address@hidden>
Date: Fri May 13 18:34:12 2016 +0200
Update port type documentation
* doc/ref/api-io.texi (I/O Extensions): Update for port type change.
---
doc/ref/api-io.texi | 25 +++++++++++++------------
1 file changed, 13 insertions(+), 12 deletions(-)
diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index 41efb35..8c91bae 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -2232,18 +2232,19 @@ the representation, will return an object equal (in the
sense of
This section describes how to implement a new port type in C. Although
ports support many operations, as a data structure they present an
opaque interface to the user. To the port implementor, you have two
-additional pieces of information: the port type code, which you allocate
-when defining your port type; and a port's ``stream'', which you
-allocate when you create a port.
+additional pieces of information: the port type, which is an opaque
+pointer allocated when defining your port type; and a port's ``stream'',
+which you allocate when you create a port.
The type code helps you identify which ports are actually yours. The
``stream'' is the private data associated with that port which you and
only you control. Get a stream from a port using the @code{SCM_STREAM}
-macro.
+macro. Note that your port methods are only ever called with ports of
+your type.
A port type is created by calling @code{scm_make_port_type}.
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))
address@hidden scm_t_port_type* 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))
Define a new port type. 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 and can be
@@ -2278,7 +2279,7 @@ Called when @code{write} is called on the port, to print
a port
description. For example, for a file port it may produce something
like: @code{#<input: /etc/passwd 3>}. Set using
address@hidden void scm_set_port_print (scm_t_bits tc, int (*print) (SCM port,
SCM dest_port, scm_print_state *pstate))
address@hidden void scm_set_port_print (scm_t_port_type *type, int (*print)
(SCM port, SCM dest_port, scm_print_state *pstate))
The first argument @var{port} is the port being printed, the second
argument @var{dest_port} is where its description should go.
@end deftypefun
@@ -2287,7 +2288,7 @@ argument @var{dest_port} is where its description should
go.
Called when the port is closed. It should free any resources used by
the port. Set using
address@hidden void scm_set_port_close (scm_t_bits tc, void (*close) (SCM port))
address@hidden void scm_set_port_close (scm_t_port_type *type, void (*close)
(SCM port))
@end deftypefun
By default, ports that are garbage collected just go away without
@@ -2296,21 +2297,21 @@ a file descriptor, or needs to make sure that its
internal buffers are
flushed even if the port is collected while it was open, then mark the
port type as needing a close on GC.
address@hidden void scm_set_port_needs_close_on_gc (scm_t_bits tc, int
needs_close_p)
address@hidden void scm_set_port_needs_close_on_gc (scm_t_port_type *type, int
needs_close_p)
@end deftypefun
@item seek
Set the current position of the port. Guile will flush read and/or
write buffers before seeking, as appropriate.
address@hidden void scm_set_port_seek (scm_t_bits tc, scm_t_off (*seek) (SCM
port, scm_t_off offset, int whence))
address@hidden void scm_set_port_seek (scm_t_port_type *type, scm_t_off (*seek)
(SCM port, scm_t_off offset, int whence))
@end deftypefun
@item truncate
Truncate the port data to be specified length. Guile will flush buffers
before hand, as appropriate. Set using
address@hidden void scm_set_port_truncate (scm_t_bits tc, void (*truncate) (SCM
port, scm_t_off length))
address@hidden void scm_set_port_truncate (scm_t_port_type *type, void
(*truncate) (SCM port, scm_t_off length))
@end deftypefun
@item random_access_p
@@ -2329,7 +2330,7 @@ nonzero value from your @code{random_access_p} function.
The default
implementation of this function returns nonzero if the port type
supplies a seek implementation.
address@hidden void scm_set_port_random_access_p (scm_t_bits tc, int
(*random_access_p) (SCM port));
address@hidden void scm_set_port_random_access_p (scm_t_port_type *type, int
(*random_access_p) (SCM port));
@end deftypefun
@item get_natural_buffer_sizes
@@ -2346,7 +2347,7 @@ bytevector. However in some cases, port implementations
may be able to
provide an appropriate default buffer size to Guile.
@deftypefun void scm_set_port_get_natural_buffer_sizes @
- (scm_t_bits tc, void (*get_natural_buffer_sizes) (SCM, size_t
*read_buf_size, size_t *write_buf_size))
+ (scm_t_port_type *type, void (*get_natural_buffer_sizes) (SCM, size_t
*read_buf_size, size_t *write_buf_size))
Fill in @var{read_buf_size} and @var{write_buf_size} with an appropriate
buffer size for this port, if one is known.
@end deftypefun
- [Guile-commits] 02/21: Implement lookahead-u8, get-u8 in Scheme, (continued)
- [Guile-commits] 02/21: Implement lookahead-u8, get-u8 in Scheme, Andy Wingo, 2016/05/16
- [Guile-commits] 10/21: Make scm_t_port private, Andy Wingo, 2016/05/16
- [Guile-commits] 17/21: Update port mode bits documentation., Andy Wingo, 2016/05/16
- [Guile-commits] 08/21: Make file/line/column fields of ports private, Andy Wingo, 2016/05/16
- [Guile-commits] 20/21: Update NEWS for release, Andy Wingo, 2016/05/16
- [Guile-commits] 18/21: Document scm_c_make_port and friends, Andy Wingo, 2016/05/16
- [Guile-commits] 01/21: %read-char speedup, Andy Wingo, 2016/05/16
- [Guile-commits] 12/21: Update port documentation, Andy Wingo, 2016/05/16
- [Guile-commits] 04/21: Add (ice-9 sports) module, Andy Wingo, 2016/05/16
- [Guile-commits] 13/21: Make scm_t_ptob_descriptor private., Andy Wingo, 2016/05/16
- [Guile-commits] 15/21: Update port type documentation,
Andy Wingo <=
- [Guile-commits] 09/21: Make port buffering fields private, Andy Wingo, 2016/05/16
- [Guile-commits] 16/21: Add SCM_OPN to mode bits when making ports, Andy Wingo, 2016/05/16
- [Guile-commits] 03/21: Beginnings of shunting ports-in-scheme off to a module, Andy Wingo, 2016/05/16
- [Guile-commits] 14/21: Use heap-allocated port types instead of ptobnums, Andy Wingo, 2016/05/16
- [Guile-commits] 11/21: Remove scm_t_port_internal, Andy Wingo, 2016/05/16
- [Guile-commits] 06/21: Remove SCM backlink in port structure, Andy Wingo, 2016/05/16
- [Guile-commits] 19/21: Remove unused type from ports-internal, Andy Wingo, 2016/05/16
- [Guile-commits] 05/21: Add random_access_p port type method, Andy Wingo, 2016/05/16