From: Marius Vollmer Date: Mon, 7 Mar 2005 21:48:18 +0000 (+0000) Subject: Talk about critical sections. X-Git-Url: https://git.hcoop.net/bpt/guile.git/commitdiff_plain/32106a5ded8c3a7f01da3943b700936c803f5acd Talk about critical sections. --- diff --git a/doc/ref/libguile-concepts.texi b/doc/ref/libguile-concepts.texi index 9fac6bf6e..c2e3b3767 100644 --- a/doc/ref/libguile-concepts.texi +++ b/doc/ref/libguile-concepts.texi @@ -589,3 +589,31 @@ of course put suitable synchronization mechanisms in place. As you can see, Guile itself is again only concerned about robustness, not about correctness: without proper synchronization, your program will likely not be correct, but the worst consequence is an error message. + +Real thread-safeness often requires that a critical section of code is +executed in a certain restricted manner. A common requirement is that +the code section is not entered a second time when it is already being +executed. Locking a mutex while in that section ensures that no other +thread will start executing it, blocking asyncs ensures that no +asynchronous code enters the section again from the current thread, +and the error checking of Guile mutexes guarantees that an error is +signalled when the current thread accidentally reenters the critical +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}. + +The macros only work reliably for critical sections that are +guaranteed to not cause a non-local exit. They also do not detect an +accidental reentry by the current thread. Thus, you should probably +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.