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 <cleme...@brinckerhoff.org> 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 > -- Jay McCarthy <j...@cs.byu.edu> Assistant Professor / Brigham Young University http://faculty.cs.byu.edu/~jay "The glory of God is Intelligence" - D&C 93 _________________________________________________ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev