mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-06-11 22:31:12 +02:00
Code Activity

(Ports): Add notes on garbage collection, and on

Browse source 
explicitly closing file ports.
(File Ports): Cross reference Ports node on explicit closing.
This commit is contained in:
Kevin Ryde 2003-06-05 00:56:33 +00:00
parent f5c6ec2fb0
commit 7d5b2929b8
1 changed files with 39 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

49
doc/ref/scheme-io.texi
View file

@ -19,19 +19,44 @@
@node Ports
@section Ports
[Concept of the port abstraction.]
Sequential input/output in Scheme is represented by operations on a
@dfn{port}. Characters can be read from an input port and
written to an output port. This chapter explains the operations
that Guile provides for working with ports.
@dfn{port}. This chapter explains the operations that Guile provides
for working with ports.
Ports are created by opening, for instance @code{open-file} for a file
(@pxref{File Ports}). Characters can be read from an input port and
written to an output port, or both on an input/output port. A port
can be closed (@pxref{Closing}) when no longer required, after which
any attempt to read or write is an error.
The formal definition of a port is very generic: an input port is
simply ``an object which can deliver characters on command,'' and
an output port is ``an object which can accept characters.''
Because this definition is so loose, it is easy to write functions
that simulate ports in software. @dfn{Soft ports} and @dfn{string
ports} are two interesting and powerful examples of this technique.
simply ``an object which can deliver characters on demand,'' and an
output port is ``an object which can accept characters.'' Because
this definition is so loose, it is easy to write functions that
simulate ports in software. @dfn{Soft ports} and @dfn{string ports}
are two interesting and powerful examples of this technique.
(@pxref{Soft Ports}, and @ref{String Ports}.)
Ports are garbage collected in the usual way (@pxref{Memory
Management}), and will be closed at that time if not already closed.
In this case any errors occuring in the close will not be reported.
Usually a program will want to explicitly close so as to be sure all
its operations have been successful. Of course if a program has
abandoned something due to an error or other condition then closing
problems are probably not of interest.
It is strongly recommended that file ports be closed explicitly when
no longer required. Most systems have limits on how many files can be
open, both on a per-process and a system-wide basis. A program that
uses many files should take care not to hit those limits. The same
applies to similar system resources such as pipes and sockets.
Note that automatic garbage collection is triggered only by memory
consumption, not by file or other resource usage, so a program cannot
rely on that to keep it away from system limits. An explicit call to
@code{gc} can of course be relied on to pick up unreferenced ports.
If program flow makes it hard to be certain when to close then this
may be an acceptable way to control resource usage.
@rnindex input-port?
@deffn {Scheme Procedure} input-port? x
@ -623,6 +648,10 @@ The following procedures are used to open file ports.
See also @ref{Ports and File Descriptors, open}, for an interface
to the Unix @code{open} system call.
Most systems have limits on how many files can be open, so it's
strongly recommended that file ports be closed explicitly when no
longer required (@pxref{Ports}).
@deffn {Scheme Procedure} open-file filename mode
@deffnx {C Function} scm_open_file (filename, mode)
Open the file whose name is @var{filename}, and return a port