summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMarius Vollmer <mvo@zagadka.de>2005-03-04 15:47:48 +0000
committerMarius Vollmer <mvo@zagadka.de>2005-03-04 15:47:48 +0000
commit9ba2fab389ffd3a464b857c583268d64570c7c0b (patch)
tree14b85815833c2c16f9e9ca07076662b7bd264db7
parente03bb21b830ff5851dc7234a09a99ca935396db6 (diff)
downloadguile-9ba2fab389ffd3a464b857c583268d64570c7c0b.tar.gz
Better docs for leaving guile mode.
-rw-r--r--doc/ref/api-scheduling.texi31
1 files changed, 19 insertions, 12 deletions
diff --git a/doc/ref/api-scheduling.texi b/doc/ref/api-scheduling.texi
index be3fd6440..4eda18a9c 100644
--- a/doc/ref/api-scheduling.texi
+++ b/doc/ref/api-scheduling.texi
@@ -310,23 +310,30 @@ guile mode. The following functions can be used to temporily leave
guile mode or to perform some common blocking operations in a supported
way.
-@deftypefn {C Function} scm_t_guile_ticket scm_leave_guile ()
-Leave guile mode and return a ticket that can be used with
-@code{scm_enter_guile} to enter it again.
+@deftypefn {C Function} scm_t_guile_ticket scm_leave_guile ()
+@deftypefnx {C Function} void scm_enter_guile (scm_t_guile_ticket ticket)
+These two functions must be called as a pair and can be used to leave
+guile mode temporarily. The call to @code{scm_leave_guile} returns a
+ticket that must be used with @code{scm_enter_guile} to match up the two
+calls.
While a thread has left guile mode, it must not call any libguile
-functions except @code{scm_enter_guile} and must not use any libguile
-macros. Also, local variables of type @code{SCM} that are allocated
-while not in guile mode are not protected from the garbage collector.
-@end deftypefn
-
-@deftypefn {C Function} void scm_enter_guile (scm_t_guile_ticket ticket)
-Enter guile mode again.
+functions except @code{scm_enter_guile}, @code{scm_with_guile},
+@code{scm_without_guile} or @code{scm_leave_guile} and must not use any
+libguile macros. Also, local variables of type @code{SCM} that are
+allocated while not in guile mode are not protected from the garbage
+collector.
+
+When used from non-guile mode, a pair of calls to @code{scm_leave_guile}
+and @code{scm_enter_guile} do nothing. In that way, you can leave guile
+mode without having to know whether the current thread is in guile mode
+or not.
@end deftypefn
@deftypefn {C Function} void *scm_without_guile (void *(*func) (void *), void *data)
-Leave guile mode, call @var{func} on @var{data}, enter guile mode and
-return the result of calling @var{func}.
+Leave guile mode as with @code{scm_leave_guile}, call @var{func} on
+@var{data}, enter guile mode as with @code{scm_enter_guile} and return
+the result of calling @var{func}.
@end deftypefn
@deftypefn {C Function} int scm_pthread_mutex_lock (pthread_mutex_t *mutex)