Re: documentation.scm close files

[Kevin Ryde]

I wrote:
>
> I'm thinking to add some words to the manual to say why it's good to
> close explicitly,

As threatened, but in the form of a revision of the "Ports" node.  The
first three paras are existing words slightly warmed-over, the rest is
new.


Ports
=====

Sequential input/output in Scheme is represented by operations on a
"port".  This chapter explains the operations that Guile provides for
working with ports.

   Ports are created by opening, for instance `open-file' for a file
(*note 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 (*note 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 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.  "Soft ports" and "string ports" are two interesting
and powerful examples of this technique.  (*note Soft Ports::, and
*Note String Ports::.)

   Ports are garbage collected in the usual way (*note 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 explicitly closed 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 to upset its own or other
program's operations by hitting those limits.  The same applies to
similar system resources such as pipes and sockets.

   If program flow means it's hard to be certain when to close, then an
acceptable substitute may be to call `gc' at suitable times to pick up
unreferenced ports.  Note that when a system limit is encountered Guile
makes no attempt to automatically garbage collect and retry.  There
would be little value in doing so, since it would remove just one of
many problems for a program trying to operate near system limits all
the time.