suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

try to clarify the async-apply protocol for callbacks

Browse Source
This commit is contained in:
Matthew Flatt 2010-08-25 12:14:28 -06:00
parent a04403a316
commit 2a387ebba2
1 changed files with 23 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
collects/scribblings/foreign/types.scrbl
View File

@ -393,20 +393,29 @@ the process may crash or misbehave.
If an @scheme[async-apply] procedure is provided, then a Racket If an @scheme[async-apply] procedure is provided, then a Racket
procedure with the generated procedure type can be applied in a 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 foreign thread (i.e., an OS-level thread other than the one used to
run Racket). In that case, @scheme[async-apply] is applied to a thunk run Racket). The call in the foreign thread is transferred to the
that encapsulates the specific callback invocation, and the foreign OS-level thread that runs Racket, but the Racket-level thread (in the
thread blocks until the thunk is called and completes; the thunk must sense of @racket[thread]) is unspecified; the job of
be called exactly once, and the callback invocation must return @scheme[async-apply] is to arrange for the callback procedure to be
normally. The @scheme[async-apply] procedure itself is called in an run in a suitable Racket thread. The @scheme[async-apply] function is
unspecified Racket thread and in atomic mode (see @scheme[atomic?] applied to a thunk that encapsulates the specific callback invocation,
above); its job is to arrange for the thunk to be called in a suitable and the foreign OS-level thread blocks until the thunk is called and
context without blocking in any synchronization. (If the callback is completes; the thunk must be called exactly once, and the callback
known to complete quickly, require no synchronization, and work invocation must return normally. The @scheme[async-apply] procedure
independent of the Racket thread in which it runs, then itself is called in atomic mode (see @scheme[atomic?] above). If the
@scheme[async-apply] can apply the thunk directly.) Foreign-thread callback is known to complete quickly, requires no synchronization,
detection to trigger @scheme[async-apply] works only when Racket is and works independent of the Racket thread in which it runs, then
compiled with OS-level thread support, which is the default for many @scheme[async-apply] can apply the thunk directly. Otherwise,
platforms. @racket[async-apply] must arrange for the thunk to be applied in a
suitable Racket thread sometime after @racket[async-apply] 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
@scheme[async-apply] works only when Racket is compiled with OS-level
thread support, which is the default for many platforms. If a callback
with an @scheme[async-apply] is called from foreign code in the same
OS-level thread that runs Racket, then the @scheme[async-apply] wrapper is
not used.
If @scheme[save-errno] is @scheme['posix], then the value of If @scheme[save-errno] is @scheme['posix], then the value of
@as-index{@tt{errno}} is saved (specific to the current thread) @as-index{@tt{errno}} is saved (specific to the current thread)