Remove port free functions; just close instead

* libguile/ports.h (scm_t_port_type_flags): Replace
  SCM_PORT_TYPE_HAS_FLUSH with SCM_PORT_TYPE_NEEDS_CLOSE_ON_GC.
  (scm_t_ptob_descriptor): Remove free function.
* libguile/ports.c (scm_set_port_needs_close_on_gc): New function.
  (scm_set_port_flush): Don't set flags.
  (scm_c_make_port_with_encoding, scm_close_port): Use the new flag to
  determine when to add a finalizer and also when to include the port in
  the weak set.
  (scm_set_port_free): Remove.
  (do_close, finalize_port): Close port instead of calling free
  function.
* libguile/r6rs-ports.c (initialize_transcoded_ports):
* libguile/vports.c (scm_make_sfptob):
* libguile/fports.c (scm_make_fptob): Mark these ports as needing close
  on GC.
* libguile/fports.c (fport_free): Remove.
* NEWS: Update.
* doc/ref/api-io.texi (Port Implementation): Update.

1 files changed, 11 insertions, 11 deletions

diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index 80a227202..c175d2eac 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -2303,14 +2303,6 @@ A pointer to a NUL terminated string: the name of the port type.  This
 is the only element of @code{scm_ptob_descriptor} which is not
 a procedure.  Set via the first argument to @code{scm_make_port_type}.
 
-@item free
-Called when the port is collected during gc.  It
-should free any resources used by the port.
-Set using
-
-@deftypefun void scm_set_port_free (scm_t_bits tc, size_t (*free) (SCM port))
-@end deftypefun
-
 @item print
 Called when @code{write} is called on the port object, to print a
 port description.  E.g., for an fport it may produce something like:
@@ -2328,13 +2320,21 @@ Not used at present.  Set using
 @end deftypefun
 
 @item close
-Called when the port is closed, unless it was collected during gc.  It
-should free any resources used by the port.
-Set using
+Called when the port is closed.  It should free any resources used by
+the port.  Set using
 
 @deftypefun void scm_set_port_close (scm_t_bits tc, int (*close) (SCM port))
 @end deftypefun
 
+By default, ports that are garbage collected just go away without
+closing.  If your port type needs to release some external resource like
+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.
+
+@deftypefun void scm_set_port_needs_close_on_gc (scm_t_bits tc, int needs_close_p)
+@end deftypefun
+
 @item write
 Accept data which is to be written using the port.  The port implementation
 may choose to buffer the data instead of processing it directly.