From b2edac3179a6a6a84c72d77d4a78223089bab67e Mon Sep 17 00:00:00 2001 From: John Clements Date: Tue, 16 Nov 2010 16:54:56 -0800 Subject: [PATCH] edited async-apply description --- collects/scribblings/foreign/types.scrbl | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/collects/scribblings/foreign/types.scrbl b/collects/scribblings/foreign/types.scrbl index 1f0c632aa3..22afd30bae 100644 --- a/collects/scribblings/foreign/types.scrbl +++ b/collects/scribblings/foreign/types.scrbl @@ -401,19 +401,22 @@ procedure with the generated procedure type can be applied in a foreign thread (i.e., an OS-level thread other than the one used to run Racket). The call in the foreign thread is transferred to the OS-level thread that runs Racket, but the Racket-level thread (in the -sense of @racket[thread]) is unspecified; the job of -@scheme[async-apply] is to arrange for the callback procedure to be -run in a suitable Racket thread. The @scheme[async-apply] function is +sense of @racket[thread]) is unspecified; the job of the provided +@scheme[async-apply] procedure is to arrange for the callback procedure to be +run in a suitable Racket thread. The given @scheme[async-apply] procedure is applied to a thunk that encapsulates the specific callback invocation, and the foreign OS-level thread blocks until the thunk is called and completes; the thunk must be called exactly once, and the callback -invocation must return normally. The @scheme[async-apply] procedure +invocation must return normally. The given @scheme[async-apply] procedure itself is called in atomic mode (see @scheme[atomic?] above). If the callback is known to complete quickly, requires no synchronization, and works independent of the Racket thread in which it runs, then -@scheme[async-apply] can apply the thunk directly. Otherwise, -@racket[async-apply] must arrange for the thunk to be applied in a -suitable Racket thread sometime after @racket[async-apply] itself +it is safe for the given +@scheme[async-apply] procedure to apply the thunk directly. Otherwise, +the given @racket[async-apply] procedure +must arrange for the thunk to be applied in a +suitable Racket thread sometime after the given +@racket[async-apply] procedure itself returns; if the thunk raises an exception or synchronizes within an unsuitable Racket-level thread, it can deadlock or otherwise damage the Racket process. Foreign-thread detection to trigger