FWIW I agree with John and disagree with Jay. On 11/16/2010 03:45 PM, Jay McCarthy wrote: > The typesetting on async-apply clearly refers to the argument rather > than to a well-known function. This is a convention of the docs that I > don't think merits special attention here, although this case may > indicate we should make a "how to read the documentation" section that > points out these conventions. > > Jay > > On Tue, Nov 16, 2010 at 1:26 PM, John Clements > <[email protected]> wrote: >> 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 >> -...@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 >> pcp062767pcs:~/plt/collects/scribblings/foreign clements$ >> >> >> _________________________________________________ >> For list-related administrative tasks: >> http://lists.racket-lang.org/listinfo/dev >> > >
_________________________________________________ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
