diff options
author | Marius Vollmer <mvo@zagadka.de> | 2006-01-29 00:23:28 +0000 |
---|---|---|
committer | Marius Vollmer <mvo@zagadka.de> | 2006-01-29 00:23:28 +0000 |
commit | 661ae7ab6be5aec4d6107902cff94dbb8952a24a (patch) | |
tree | d3e367c7f0dfd442645c5c2e1c87f4f4a7fc54c5 /doc | |
parent | 15ccf10bf2d7cb15ec46f2eb62c6eb86827c9108 (diff) | |
download | guile-661ae7ab6be5aec4d6107902cff94dbb8952a24a.tar.gz |
Renamed the "frames" that are related to dynamic-wind to "dynamic
contexts. Renamed all functions from scm_frame_ to scm_dynwind_.
Updated documentation.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ref/ChangeLog | 6 | ||||
-rw-r--r-- | doc/ref/api-compound.texi | 31 | ||||
-rw-r--r-- | doc/ref/api-control.texi | 216 | ||||
-rwxr-xr-x | doc/ref/api-data.texi | 7 | ||||
-rw-r--r-- | doc/ref/api-io.texi | 12 | ||||
-rw-r--r-- | doc/ref/api-memory.texi | 4 | ||||
-rw-r--r-- | doc/ref/api-scheduling.texi | 58 | ||||
-rw-r--r-- | doc/ref/libguile-concepts.texi | 24 |
8 files changed, 182 insertions, 176 deletions
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog index d2a6dfa21..b195755d4 100644 --- a/doc/ref/ChangeLog +++ b/doc/ref/ChangeLog @@ -1,9 +1,13 @@ +2006-01-29 Marius Vollmer <mvo@zagadka.de> + + Renamed the "frames" that are related to dynamic-wind to "dynamic + contexts. Renamed all functions from scm_frame_ to scm_dynwind_. + Updated documentation. 2005-12-19 Ludovic Courtès <ludovic.courtes@laas.fr> * api-data.texi (Operations Related to Symbols): Documented `scm_take_locale_symbol ()'. - 2005-12-15 Kevin Ryde <user42@zip.com.au> diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi index 159ab6070..a47b2d28e 100644 --- a/doc/ref/api-compound.texi +++ b/doc/ref/api-compound.texi @@ -2326,21 +2326,22 @@ error is signalled. the danger of a deadlock. In a multi-threaded program, you will need additional synchronization to avoid modifying reserved arrays.) -You must take care to always unreserve an array after reserving it, also -in the presence of non-local exits. To simplify this, reserving and -unreserving work like a frame (@pxref{Frames}): a call to -@code{scm_array_get_handle} can be thought of as beginning a frame and -@code{scm_array_handle_release} as ending it. When a non-local exit -happens between these two calls, the array is implicitely unreserved. +You must take care to always unreserve an array after reserving it, +also in the presence of non-local exits. To simplify this, reserving +and unreserving work like a dynwind context (@pxref{Dynamic Wind}): a +call to @code{scm_array_get_handle} can be thought of as beginning a +dynwind context and @code{scm_array_handle_release} as ending it. +When a non-local exit happens between these two calls, the array is +implicitely unreserved. That is, you need to properly pair reserving and unreserving in your code, but you don't need to worry about non-local exits. -These calls and other pairs of calls that establish dynamic contexts -need to be properly nested. If you begin a frame prior to reserving an -array, you need to unreserve the array before ending the frame. -Likewise, when reserving two or more arrays in a certain order, you need -to unreserve them in the opposite order. +These calls and other pairs of calls that establish dynwind contexts +need to be properly nested. If you begin a context prior to reserving +an array, you need to unreserve the array before ending the context. +Likewise, when reserving two or more arrays in a certain order, you +need to unreserve them in the opposite order. Once you have reserved an array and have retrieved the pointer to its elements, you must figure out the layout of the elements in memory. @@ -2356,11 +2357,11 @@ indices. The scalar position then is the offset of the element with the given indices from the start of the storage block of the array. In Guile, this mapping function is restricted to be @dfn{affine}: all -mapping function of Guile arrays can be written as @code{p = b + +mapping functions of Guile arrays can be written as @code{p = b + c[0]*i[0] + c[1]*i[1] + ... + c[n-1]*i[n-1]} where @code{i[k]} is the -@nicode{k}th index and @code{n} is the rank of the array. For example, -a matrix of size 3x3 would have @code{b == 0}, @code{c[0] == 3} and -@code{c[1] == 1}. When you transpose this matrix (with +@nicode{k}th index and @code{n} is the rank of the array. For +example, a matrix of size 3x3 would have @code{b == 0}, @code{c[0] == +3} and @code{c[1] == 1}. When you transpose this matrix (with @code{transpose-array}, say), you will get an array whose mapping function has @code{b == 0}, @code{c[0] == 1} and @code{c[1] == 3}. diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi index efdb4531e..247f1afc8 100644 --- a/doc/ref/api-control.texi +++ b/doc/ref/api-control.texi @@ -20,8 +20,7 @@ flow of Scheme affects C code. * Multiple Values:: Returning and accepting multiple values. * Exceptions:: Throwing and catching exceptions. * Error Reporting:: Procedures for signaling errors. -* Dynamic Wind:: Guarding against non-local entrance/exit. -* Frames:: Another way to handle non-localness +* Dynamic Wind:: Dealing with non-local entrance/exit. * Handling Errors:: How to handle errors in C code. @end menu @@ -463,8 +462,7 @@ flow going on as normal. @code{dynamic-wind} (@pxref{Dynamic Wind}) can be used to ensure setup and cleanup code is run when a program locus is resumed or abandoned -through the continuation mechanism. C code can use @dfn{frames} -(@pxref{Frames}). +through the continuation mechanism. @sp 1 Continuations are a powerful mechanism, and can be used to implement @@ -1013,6 +1011,71 @@ if an exception occurs then @code{#f} is returned instead. @node Dynamic Wind @subsection Dynamic Wind +For Scheme code, the fundamental procedure to react to non-local entry +and exits of dynamic contexts is @code{dynamic-wind}. C code could +use @code{scm_internal_dynamic_wind}, but since C does not allow the +convenient construction of anonymous procedures that close over +lexical variables, this will be, well, inconvenient. + +Therefore, Guile offers the functions @code{scm_dynwind_begin} and +@code{scm_dynwind_end} to delimit a dynamic extent. Within this +dynamic extent, which is calles a @dfn{dynwind context}, you can +perform various @dfn{dynwind actions} that control what happens when +the dynwind context is entered or left. For example, you can register +a cleanup routine with @code{scm_dynwind_unwind_handler} that is +executed when the context is left. There are several other more +specialized dynwind actions as well, for example to temporarily block +the execution of asyncs or to temporarily change the current output +port. They are described elsewhere in this manual. + +Here is an example that shows how to prevent memory leaks. + +@example + +/* Suppose there is a function called FOO in some library that you + would like to make available to Scheme code (or to C code that + follows the Scheme conventions). + + FOO takes two C strings and returns a new string. When an error has + occurred in FOO, it returns NULL. +*/ + +char *foo (char *s1, char *s2); + +/* SCM_FOO interfaces the C function FOO to the Scheme way of life. + It takes care to free up all temporary strings in the case of + non-local exits. + */ + +SCM +scm_foo (SCM s1, SCM s2) +@{ + char *c_s1, *c_s2, *c_res; + + scm_dynwind_begin (0); + + c_s1 = scm_to_locale_string (s1); + + /* Call 'free (c_s1)' when the dynwind context is left. + */ + scm_dynwind_unwind_handler (free, c_s1, SCM_F_WIND_EXPLICITLY); + + c_s2 = scm_to_locale_string (s2); + + /* Same as above, but more concisely. + */ + scm_dynwind_free (c_s2); + + c_res = foo (c_s1, c_s2); + if (c_res == NULL) + scm_memory_error ("foo"); + + scm_dynwind_end (); + + return scm_take_locale_string (res); +@} +@end example + @rnindex dynamic-wind @deffn {Scheme Procedure} dynamic-wind in_guard thunk out_guard @deffnx {C Function} scm_dynamic_wind (in_guard, thunk, out_guard) @@ -1066,95 +1129,29 @@ a-cont @end lisp @end deffn -@node Frames -@subsection Frames - -For Scheme code, the fundamental procedure to react to non-local entry -and exits of dynamic contexts is @code{dynamic-wind}. C code could use -@code{scm_internal_dynamic_wind}, but since C does not allow the -convenient construction of anonymous procedures that close over lexical -variables, this will be, well, inconvenient. Instead, C code can use -@dfn{frames}. - -Guile offers the functions @code{scm_frame_begin} and -@code{scm_frame_end} to delimit a dynamic extent. Within this dynamic -extent, which is called a @dfn{frame}, you can perform various -@dfn{frame actions} that control what happens when the frame is entered -or left. For example, you can register a cleanup routine with -@code{scm_frame_unwind} that is executed when the frame is left. There are -several other more specialized frame actions as well, for example to -temporarily block the execution of asyncs or to temporarily change the -current output port. They are described elsewhere in this manual. - -Here is an example that shows how to prevent memory leaks. - -@example - -/* Suppose there is a function called FOO in some library that you - would like to make available to Scheme code (or to C code that - follows the Scheme conventions). - - FOO takes two C strings and returns a new string. When an error has - occurred in FOO, it returns NULL. -*/ - -char *foo (char *s1, char *s2); - -/* SCM_FOO interfaces the C function FOO to the Scheme way of life. - It takes care to free up all temporary strings in the case of - non-local exits. - */ - -SCM -scm_foo (SCM s1, SCM s2) -@{ - char *c_s1, *c_s2, *c_res; - - scm_frame_begin (0); - - c_s1 = scm_to_locale_string (s1); - - /* Call 'free (c_s1)' when the frame is left. - */ - scm_frame_unwind_handler (free, c_s1, SCM_F_WIND_EXPLICITLY); - - c_s2 = scm_to_locale_string (s2); - - /* Same as above, but more concisely. - */ - scm_frame_free (c_s2); - - c_res = foo (c_s1, c_s2); - if (c_res == NULL) - scm_memory_error ("foo"); - - scm_frame_end (); - - return scm_take_locale_string (res); -@} -@end example - -@deftp {C Type} scm_t_frame_flags +@deftp {C Type} scm_t_dynwind_flags This is an enumeration of several flags that modify the behavior of -@code{scm_begin_frame}. The flags are listed in the following table. +@code{scm_dynwind_begin}. The flags are listed in the following +table. @table @code -@item SCM_F_FRAME_REWINDABLE -The frame is @dfn{rewindable}. This means that it can be reentered -non-locally (via the invokation of a continuation). The default is that -a frame can not be reentered non-locally. +@item SCM_F_DYNWIND_REWINDABLE +The dynamic context is @dfn{rewindable}. This means that it can be +reentered non-locally (via the invokation of a continuation). The +default is that a dynwind context can not be reentered non-locally. @end table @end deftp -@deftypefn {C Function} void scm_frame_begin (scm_t_frame_flags flags) -The function @code{scm_begin_frame} starts a new frame and makes it the -`current' one. +@deftypefn {C Function} void scm_dynwind_begin (scm_t_dynwind_flags flags) +The function @code{scm_dynwind_begin} starts a new dynamic context and +makes it the `current' one. -The @var{flags} argument determines the default behavior of the frame. -For normal frames, use 0. This will result in a frame that can not be -reentered with a captured continuation. When you are prepared to handle -reentries, include @code{SCM_F_FRAME_REWINDABLE} in @var{flags}. +The @var{flags} argument determines the default behavior of the +context. Normally, use 0. This will result in a context that can not +be reentered with a captured continuation. When you are prepared to +handle reentries, include @code{SCM_F_DYNWIND_REWINDABLE} in +@var{flags}. Being prepared for reentry means that the effects of unwind handlers can be undone on reentry. In the example above, we want to prevent a @@ -1163,51 +1160,54 @@ frees the memory. But once the memory is freed, we can not get it back on reentry. Thus reentry can not be allowed. The consequence is that continuations become less useful when -non-reenterable frames are captured, but you don't need to worry about -that too much. - -The frame is ended either implicitly when a non-local exit happens, or -explicitly with @code{scm_end_frame}. You must make sure that a frame -is indeed ended properly. If you fail to call @code{scm_end_frame} -for each @code{scm_begin_frame}, the behavior is undefined. +non-reenterable contexts are captured, but you don't need to worry +about that too much. + +The context is ended either implicitly when a non-local exit happens, +or explicitly with @code{scm_dynwind_end}. You must make sure that a +dynwind context is indeed ended properly. If you fail to call +@code{scm_dynwind_end} for each @code{scm_dynwind_begin}, the behavior +is undefined. @end deftypefn -@deftypefn {C Function} void scm_frame_end () -End the current frame explicitly and make the previous frame current. +@deftypefn {C Function} void scm_dynwind_end () +End the current dynamic context explicitly and make the previous one +current. @end deftypefn @deftp {C Type} scm_t_wind_flags This is an enumeration of several flags that modify the behavior of -@code{scm_on_unwind_handler} and @code{scm_on_rewind_handler}. The -flags are listed in the following table. +@code{scm_dynwind_unwind_handler} and +@code{scm_dynwind_rewind_handler}. The flags are listed in the +following table. @table @code @item SCM_F_WIND_EXPLICITLY @vindex SCM_F_WIND_EXPLICITLY -The registered action is also carried out when the frame is entered or -left locally. +The registered action is also carried out when the dynwind context is +entered or left locally. @end table @end deftp -@deftypefn {C Function} void scm_frame_unwind_handler (void (*func)(void *), void *data, scm_t_wind_flags flags) -@deftypefnx {C Function} void scm_frame_unwind_handler_with_scm (void (*func)(SCM), SCM data, scm_t_wind_flags flags) +@deftypefn {C Function} void scm_dynwind_unwind_handler (void (*func)(void *), void *data, scm_t_wind_flags flags) +@deftypefnx {C Function} void scm_dynwind_unwind_handler_with_scm (void (*func)(SCM), SCM data, scm_t_wind_flags flags) Arranges for @var{func} to be called with @var{data} as its arguments -when the current frame ends implicitly. If @var{flags} contains -@code{SCM_F_WIND_EXPLICITLY}, @var{func} is also called when the frame -ends explicitly with @code{scm_frame_end}. +when the current context ends implicitly. If @var{flags} contains +@code{SCM_F_WIND_EXPLICITLY}, @var{func} is also called when the +context ends explicitly with @code{scm_dynwind_end}. -The function @code{scm_frame_unwind_handler_with_scm} takes care that +The function @code{scm_dynwind_unwind_handler_with_scm} takes care that @var{data} is protected from garbage collection. @end deftypefn -@deftypefn {C Function} void scm_frame_rewind_handler (void (*func)(void *), void *data, scm_t_wind_flags flags) -@deftypefnx {C Function} void scm_frame_rewind_handler_with_scm (void (*func)(SCM), SCM data, scm_t_wind_flags flags) +@deftypefn {C Function} void scm_dynwind_rewind_handler (void (*func)(void *), void *data, scm_t_wind_flags flags) +@deftypefnx {C Function} void scm_dynwind_rewind_handler_with_scm (void (*func)(SCM), SCM data, scm_t_wind_flags flags) Arrange for @var{func} to be called with @var{data} as its argument when -the current frame is restarted by rewinding the stack. When @var{flags} +the current context is restarted by rewinding the stack. When @var{flags} contains @code{SCM_F_WIND_EXPLICITLY}, @var{func} is called immediately as well. -The function @code{scm_frame_rewind_handler_with_scm} takes care that +The function @code{scm_dynwind_rewind_handler_with_scm} takes care that @var{data} is protected from garbage collection. @end deftypefn diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi index 99cd43a3e..61847e3a4 100755 --- a/doc/ref/api-data.texi +++ b/doc/ref/api-data.texi @@ -3603,8 +3603,8 @@ listed in this section, you are `future-proof'. Converting a Scheme string to a C string will often allocate fresh memory to hold the result. You must take care that this memory is properly freed eventually. In many cases, this can be achieved by -using @code{scm_frame_free} inside an appropriate frame, -@xref{Frames}. +using @code{scm_dynwind_free} inside an appropriate dynwind context, +@xref{Dynamic Wind}. @deftypefn {C Function} SCM scm_from_locale_string (const char *str) @deftypefnx {C Function} SCM scm_from_locale_stringn (const char *str, size_t len) @@ -3632,7 +3632,8 @@ can then use @var{str} directly as its internal representation. @deftypefnx {C Function} {char *} scm_to_locale_stringn (SCM str, size_t *lenp) Returns a C string in the current locale encoding with the same contents as @var{str}. The C string must be freed with @code{free} -eventually, maybe by using @code{scm_frame_free}, @xref{Frames}. +eventually, maybe by using @code{scm_dynwind_free}, @xref{Dynamic +Wind}. For @code{scm_to_locale_string}, the returned string is null-terminated and an error is signalled when @var{str} contains diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi index f0ea5c3d4..ab79e4fb0 100644 --- a/doc/ref/api-io.texi +++ b/doc/ref/api-io.texi @@ -670,16 +670,16 @@ Change the ports returned by @code{current-input-port}, so that they use the supplied @var{port} for input or output. @end deffn -@deftypefn {C Function} void scm_frame_current_input_port (SCM port) -@deftypefnx {C Function} void scm_frame_current_output_port (SCM port) -@deftypefnx {C Function} void scm_frame_current_error_port (SCM port) +@deftypefn {C Function} void scm_dynwind_current_input_port (SCM port) +@deftypefnx {C Function} void scm_dynwind_current_output_port (SCM port) +@deftypefnx {C Function} void scm_dynwind_current_error_port (SCM port) These functions must be used inside a pair of calls to -@code{scm_frame_begin} and @code{scm_frame_end} (@pxref{Frames}). -During the dynamic extent of the frame, the indicated port is set to +@code{scm_dynwind_begin} and @code{scm_dynwind_end} (@pxref{Dynamic +Wind}). During the dynwind context, the indicated port is set to @var{port}. More precisely, the current port is swapped with a `backup' value -whenever the frame is entered or left. The backup value is +whenever the dynwind context is entered or left. The backup value is initialized with the @var{port} argument. @end deftypefn diff --git a/doc/ref/api-memory.texi b/doc/ref/api-memory.texi index 81f754829..32d39982c 100644 --- a/doc/ref/api-memory.texi +++ b/doc/ref/api-memory.texi @@ -124,8 +124,8 @@ in place of @code{realloc} when appropriate, and @code{scm_gc_calloc} and @code{scm_calloc}, to be used in place of @code{calloc} when appropriate. -The function @code{scm_frame_free} can be useful when memory should be -freed when a frame is left, @xref{Frames}. +The function @code{scm_dynwind_free} can be useful when memory should +be freed when a dynwind context, @xref{Dynamic Wind}. For really specialized needs, take at look at @code{scm_gc_register_collectable_memory} and diff --git a/doc/ref/api-scheduling.texi b/doc/ref/api-scheduling.texi index 00e8befe1..2401b0684 100644 --- a/doc/ref/api-scheduling.texi +++ b/doc/ref/api-scheduling.texi @@ -115,9 +115,9 @@ them temporarily. In addition to the C versions of @code{call-with-blocked-asyncs} and @code{call-with-unblocked-asyncs}, C code can use -@code{scm_frame_block_asyncs} and @code{scm_frame_unblock_asyncs} -inside a @dfn{frame} (@pxref{Frames}) to block or unblock system asyncs -temporarily. +@code{scm_dynwind_block_asyncs} and @code{scm_dynwind_unblock_asyncs} +inside a @dfn{dynamic context} (@pxref{Dynamic Wind}) to block or +unblock system asyncs temporarily. @deffn {Scheme Procedure} system-async-mark proc [thread] @deffnx {C Function} scm_system_async_mark (proc) @@ -159,16 +159,16 @@ returned by @var{proc}. For the first two variants, call @var{proc} with no arguments; for the third, call it with @var{data}. @end deffn -@deftypefn {C Function} void scm_frame_block_asyncs () +@deftypefn {C Function} void scm_dynwind_block_asyncs () This function must be used inside a pair of calls to -@code{scm_frame_begin} and @code{scm_frame_end} (@pxref{Frames}). -During the dynamic extent of the frame, asyncs are blocked by one level. +@code{scm_dynwind_begin} and @code{scm_dynwind_end} (@pxref{Dynamic +Wind}). During the dynwind context, asyncs are blocked by one level. @end deftypefn -@deftypefn {C Function} void scm_frame_unblock_asyncs () +@deftypefn {C Function} void scm_dynwind_unblock_asyncs () This function must be used inside a pair of calls to -@code{scm_frame_begin} and @code{scm_frame_end} (@pxref{Frames}). -During the dynamic extent of the frame, asyncs are unblocked by one +@code{scm_dynwind_begin} and @code{scm_dynwind_end} (@pxref{Dynamic +Wind}). During the dynwind context, asyncs are unblocked by one level. @end deftypefn @@ -355,9 +355,9 @@ blocked in @code{lock-mutex}, the wait is interrupted and the async is executed. When the async returns, the wait resumes. @end deffn -@deftypefn {C Function} void scm_frame_lock_mutex (SCM mutex) -Arrange for @var{mutex} to be locked whenever the current frame is -entered and to be unlocked when it is exited. +@deftypefn {C Function} void scm_dynwind_lock_mutex (SCM mutex) +Arrange for @var{mutex} to be locked whenever the current dynwind +context is entered and to be unlocked when it is exited. @end deftypefn @deffn {Scheme Procedure} try-mutex mx @@ -523,16 +523,16 @@ This means that no non-local exit (such as a signalled error) might happen, for example. @end deffn -@deftypefn {C Function} void scm_frame_critical_section (SCM mutex) -Call @code{scm_frame_lock_mutex} on @var{mutex} and call -@code{scm_frame_block_asyncs}. When @var{mutex} is false, a recursive +@deftypefn {C Function} void scm_dynwind_critical_section (SCM mutex) +Call @code{scm_dynwind_lock_mutex} on @var{mutex} and call +@code{scm_dynwind_block_asyncs}. When @var{mutex} is false, a recursive mutex provided by Guile is used instead. -The effect of a call to @code{scm_frame_critical_section} is that the -current frame (@pxref{Frames}) turns into a critical section. Because -of the locked mutex, no second thread can enter it concurrently and -because of the blocked asyncs, no system async can reenter it from the -current thread. +The effect of a call to @code{scm_dynwind_critical_section} is that +the current dynwind context (@pxref{Dynamic Wind}) turns into a +critical section. Because of the locked mutex, no second thread can +enter it concurrently and because of the blocked asyncs, no system +async can reenter it from the current thread. When the current thread reenters the critical section anyway, the kind of @var{mutex} determines what happens: When @var{mutex} is recursive, @@ -633,15 +633,15 @@ The function @code{scm_c_with_fluid} is similar but only allows one fluid to be set instead of a list. @end deftypefn -@deftypefn {C Function} void scm_frame_fluid (SCM fluid, SCM val) +@deftypefn {C Function} void scm_dynwind_fluid (SCM fluid, SCM val) This function must be used inside a pair of calls to -@code{scm_frame_begin} and @code{scm_frame_end} (@pxref{Frames}). -During the dynamic extent of the frame, the fluid @var{fluid} is set -to @var{val}. +@code{scm_dynwind_begin} and @code{scm_dynwind_end} (@pxref{Dynamic +Wind}). During the dynwind context, the fluid @var{fluid} is set to +@var{val}. More precisely, the value of the fluid is swapped with a `backup' -value whenever the frame is entered or left. The backup value is -initialized with the @var{val} argument. +value whenever the dynwind context is entered or left. The backup +value is initialized with the @var{val} argument. @end deftypefn @deffn {Scheme Procedure} make-dynamic-state [parent] @@ -678,9 +678,9 @@ Call @var{proc} while @var{state} is the current dynamic state object. @end deffn -@deftypefn {C Procedure} void scm_frame_current_dynamic_state (SCM state) -Set the current dynamic state to @var{state} for the dynamic extent of -the current frame. +@deftypefn {C Procedure} void scm_dynwind_current_dynamic_state (SCM state) +Set the current dynamic state to @var{state} for the current dynwind +context. @end deftypefn @deftypefn {C Procedure} {void *} scm_c_with_dynamic_state (SCM state, void *(*func)(void *), void *data) diff --git a/doc/ref/libguile-concepts.texi b/doc/ref/libguile-concepts.texi index c969bdaa9..6fef7a79a 100644 --- a/doc/ref/libguile-concepts.texi +++ b/doc/ref/libguile-concepts.texi @@ -377,11 +377,11 @@ its previous value when @code{with-output-to-port} returns normally or when it is exited non-locally. Likewise, the port needs to be set again when control enters non-locally. -Scheme code can use the @code{dynamic-wind} function to arrange for the -setting and resetting of the global state. C code could use the -corresponding @code{scm_internal_dynamic_wind} function, but it might -prefer to use the @dfn{frames} concept that is more natural for C code, -(@pxref{Frames}). +Scheme code can use the @code{dynamic-wind} function to arrange for +the setting and resetting of the global state. C code can use the +corresponding @code{scm_internal_dynamic_wind} function, or a +@code{scm_dynwind_begin}/@code{scm_dynwind_end} pair together with +suitable 'dynwind actions' (@pxref{Dynamic Wind}). Instead of coping with non-local control flow, you can also prevent it by erecting a @emph{continuation barrier}, @xref{Continuation @@ -407,7 +407,7 @@ including a non-local exit although @code{scm_cons} would not ordinarily do such a thing on its own. If you do not want to allow the running of asynchronous signal handlers, -you can block them temporarily with @code{scm_frame_block_asyncs}, for +you can block them temporarily with @code{scm_dynwind_block_asyncs}, for example. See @xref{System asyncs}. Since signal handling in Guile relies on safe points, you need to make @@ -602,8 +602,8 @@ section via recursive function calls. Guile provides two mechanisms to support critical sections as outlined above. You can either use the macros @code{SCM_CRITICAL_SECTION_START} and @code{SCM_CRITICAL_SECTION_END} -for very simple sections; or use a frame together with a call to -@code{scm_frame_critical_section}. +for very simple sections; or use a dynwind context together with a +call to @code{scm_dynwind_critical_section}. The macros only work reliably for critical sections that are guaranteed to not cause a non-local exit. They also do not detect an @@ -612,7 +612,7 @@ only use them to delimit critical sections that do not contain calls to libguile functions or to other external functions that might do complicated things. -The function @code{scm_frame_critical_section}, on the other hand, -will correctly deal with non-local exits because it requires a frame. -Also, by using a separate mutex for each critical section, it can -detect accidental reentries. +The function @code{scm_dynwind_critical_section}, on the other hand, +will correctly deal with non-local exits because it requires a dynwind +context. Also, by using a separate mutex for each critical section, +it can detect accidental reentries. |