mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-06-09 21:40:33 +02:00
Code Activity

Update port type documentation

Browse source 
* doc/ref/api-io.texi (I/O Extensions): Update for port type change.
This commit is contained in:
Andy Wingo 2016-05-13 18:34:12 +02:00
parent cd51ce81d0
commit 9322902d02
1 changed files with 13 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -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 This section describes how to implement a new port type in C. Although
ports support many operations, as a data structure they present an ports support many operations, as a data structure they present an
opaque interface to the user. To the port implementor, you have two opaque interface to the user. To the port implementor, you have two
additional pieces of information: the port type code, which you allocate additional pieces of information: the port type, which is an opaque
when defining your port type; and a port's ``stream'', which you pointer allocated when defining your port type; and a port's ``stream'',
allocate when you create a port. which you allocate when you create a port.
The type code helps you identify which ports are actually yours. The The type code helps you identify which ports are actually yours. The
``stream'' is the private data associated with that port which you and ``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} 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}. A port type is created by calling @code{scm_make_port_type}.
@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)) @deftypefun 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} Define a new port type. The @var{name}, @var{read} and @var{write}
parameters are initial values for those port type fields, as described parameters are initial values for those port type fields, as described
below. The other fields are initialized with default values and can be 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 description. For example, for a file port it may produce something
like: @code{#<input: /etc/passwd 3>}. Set using like: @code{#<input: /etc/passwd 3>}. Set using
@deftypefun void scm_set_port_print (scm_t_bits tc, int (*print) (SCM port, SCM dest_port, scm_print_state *pstate)) @deftypefun 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 The first argument @var{port} is the port being printed, the second
argument @var{dest_port} is where its description should go. argument @var{dest_port} is where its description should go.
@end deftypefun @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 Called when the port is closed. It should free any resources used by
the port. Set using the port. Set using
@deftypefun void scm_set_port_close (scm_t_bits tc, void (*close) (SCM port)) @deftypefun void scm_set_port_close (scm_t_port_type *type, void (*close) (SCM port))
@end deftypefun @end deftypefun
By default, ports that are garbage collected just go away without 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 flushed even if the port is collected while it was open, then mark the
port type as needing a close on GC. port type as needing a close on GC.
@deftypefun void scm_set_port_needs_close_on_gc (scm_t_bits tc, int needs_close_p) @deftypefun void scm_set_port_needs_close_on_gc (scm_t_port_type *type, int needs_close_p)
@end deftypefun @end deftypefun
@item seek @item seek
Set the current position of the port. Guile will flush read and/or Set the current position of the port. Guile will flush read and/or
write buffers before seeking, as appropriate. write buffers before seeking, as appropriate.
@deftypefun void scm_set_port_seek (scm_t_bits tc, scm_t_off (*seek) (SCM port, scm_t_off offset, int whence)) @deftypefun void scm_set_port_seek (scm_t_port_type *type, scm_t_off (*seek) (SCM port, scm_t_off offset, int whence))
@end deftypefun @end deftypefun
@item truncate @item truncate
Truncate the port data to be specified length. Guile will flush buffers Truncate the port data to be specified length. Guile will flush buffers
before hand, as appropriate. Set using before hand, as appropriate. Set using
@deftypefun void scm_set_port_truncate (scm_t_bits tc, void (*truncate) (SCM port, scm_t_off length)) @deftypefun void scm_set_port_truncate (scm_t_port_type *type, void (*truncate) (SCM port, scm_t_off length))
@end deftypefun @end deftypefun
@item random_access_p @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 implementation of this function returns nonzero if the port type
supplies a seek implementation. supplies a seek implementation.
@deftypefun void scm_set_port_random_access_p (scm_t_bits tc, int (*random_access_p) (SCM port)); @deftypefun void scm_set_port_random_access_p (scm_t_port_type *type, int (*random_access_p) (SCM port));
@end deftypefun @end deftypefun
@item get_natural_buffer_sizes @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. provide an appropriate default buffer size to Guile.
@deftypefun void scm_set_port_get_natural_buffer_sizes @ @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. 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 @end deftypefun