Add interface to disable automatic finalization

[bpt/guile.git] / doc / ref / api-smobs.texi

diff --git a/doc/ref/api-smobs.texi b/doc/ref/api-smobs.texi
index cb2034c..cfabd39 100644 (file)
--- a/doc/ref/api-smobs.texi
+++ b/doc/ref/api-smobs.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
-@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2013
+@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2013, 2014
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -60,6 +60,36 @@ memory is automatically reclaimed by the garbage collector when it is no
 longer needed (@pxref{Memory Blocks, @code{scm_gc_malloc}}).
 @end deftypefn
 
+Smob free functions must be thread-safe.  @xref{Garbage Collecting
+Smobs}, for a discussion on finalizers and concurrency.  If you are
+embedding Guile in an application that is not thread-safe, and you
+define smob types that need finalization, you might want to disable
+automatic finalization, and arrange to call
+@code{scm_manually_run_finalizers ()} yourself.
+
+@deftypefn {C Function} int scm_set_automatic_finalization_enabled (int enabled_p)
+Enable or disable automatic finalization.  By default, Guile arranges to
+invoke object finalizers automatically, in a separate thread if
+possible.  Passing a zero value for @var{enabled_p} will disable
+automatic finalization for Guile as a whole.  If you disable automatic
+finalization, you will have to call @code{scm_run_finalizers ()}
+periodically.
+
+Unlike most other Guile functions, you can call
+@code{scm_set_automatic_finalization_enabled} before Guile has been
+initialized.
+
+Return the previous status of automatic finalization.
+@end deftypefn
+
+@deftypefn {C Function} int scm_run_finalizers (void)
+Invoke any pending finalizers.  Returns the number of finalizers that
+were invoked.  This function should be called when automatic
+finalization is disabled, though it may be called if it is enabled as
+well.
+@end deftypefn
+
+
 @cindex precise marking
 
 @deftypefn {C Function} void scm_set_smob_mark (scm_t_bits tc, SCM (*mark) (SCM obj))
@@ -124,9 +154,9 @@ Else, signal an error.
 @end deftypefn
 
 @deftypefn {C Macro} int SCM_SMOB_PREDICATE (scm_t_bits tag, SCM exp)
-Return true iff @var{exp} is a smob instance of the type indicated by
-@var{tag}.  The expression @var{exp} can be evaluated more than once,
-so it shouldn't contain any side effects.
+Return true if @var{exp} is a smob instance of the type indicated by
+@var{tag}, or false otherwise.  The expression @var{exp} can be
+evaluated more than once, so it shouldn't contain any side effects.
 @end deftypefn
 
 @deftypefn {C Function} SCM scm_new_smob (scm_t_bits tag, void *data)