Add interface to disable automatic finalization

* libguile/finalizers.h:
* libguile/finalizers.c (run_finalizers_async_thunk): Call the new
  scm_run_finalizers helper.
  (scm_set_automatic_finalization_enabled, scm_run_finalizers): New
  functions.
  (scm_init_finalizers): Only set a finalizer notifier if automatic
  finalization is enabled.

* doc/ref/libguile-smobs.texi (Garbage Collecting Smobs): Add discussion
  of concurrency.

* doc/ref/api-smobs.texi (Smobs): Document new functions.

1 files changed, 31 insertions, 1 deletions

diff --git a/doc/ref/api-smobs.texi b/doc/ref/api-smobs.texi
index 345bf7cbd..cfabd3988 100644
--- 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))