[racket-dev] proposed clarification to "async-apply" docs

My quick reading of the documentation for the #:async-apply argument to the _fun form led to a misunderstanding; the docs seemed to be suggesting that some built-in 'async-apply' procedure was doing all of these magical things, whereas the point was to indicate that the *user* must provide an async-apply that behaves correctly.  I wound up going through and replacing 'async-apply' with 'the given async-apply procedure' in about five places. I think the text is clearer now; let me know if I shouldn't commit these changes. Otherwise, I'll commit them locally and push them sometime soon.

John



pcp062767pcs:~/plt/collects/scribblings/foreign clements$ git diff types.scrbl 
diff --git a/collects/scribblings/foreign/types.scrbl b/collects/scribblings/foreign/types.scrbl
index 9d753ac..233f48d 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
- at 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
+ at 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
- at scheme[async-apply] can apply the thunk directly. Otherwise,
- at 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 
+ at 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
+ at 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
pcp062767pcs:~/plt/collects/scribblings/foreign clements$ 

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4669 bytes
Desc: not available
URL: <http://lists.racket-lang.org/dev/archive/attachments/20101116/14bddf23/attachment.p7s>