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

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
<clements at 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
> - 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$
>
>
> _________________________________________________
>  For list-related administrative tasks:
>  http://lists.racket-lang.org/listinfo/dev
>



-- 
Jay McCarthy <jay at cs.byu.edu>
Assistant Professor / Brigham Young University
http://faculty.cs.byu.edu/~jay

"The glory of God is Intelligence" - D&C 93