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

ffi/unsafe: document make-late-weak-{box,hasheq}

Browse Source 
Closes #1828
This commit is contained in:
Matthew Flatt 2018-06-20 18:04:26 -06:00
parent f58b99aa74
commit f3fc583c6f
1 changed files with 23 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
pkgs/racket-doc/scribblings/foreign/pointers.scrbl
View File

@ -299,10 +299,15 @@ Frees an immobile cell created by @racket[malloc-immobile-cell].}
@defproc[(register-finalizer [obj any/c] [finalizer (any/c . -> . any)]) void?]{ @defproc[(register-finalizer [obj any/c] [finalizer (any/c . -> . any)]) void?]{
Registers a finalizer procedure @racket[finalizer-proc] with the given Registers a finalizer procedure @racket[finalizer-proc] with the given
@racket[obj], which can be any Racket (GC-able) object. The finalizer @racket[obj], which can be any Racket (GC-able) object. The finalizer
is registered with a will executor; see is registered with a ``late'' @tech[#:doc reference.scrbl]{will
@racket[make-will-executor]. The finalizer is invoked when executor} that makes wills ready for a value only after all
@racket[obj] is about to be collected. @tech[#:doc reference.scrbl]{weak box}es referencing the value have
been cleared, which implies that the value is unreachable and no
normal @tech[#:doc reference.scrbl]{will executor} has a will ready
for the value. The finalizer is invoked when the will for @racket[obj]
becomes ready in the ``late'' will executor, which means that the
value is unreachable (even from wills) by safe code.
The finalizer is invoked in a thread that is in charge of triggering The finalizer is invoked in a thread that is in charge of triggering
will executors for @racket[register-finalizer]. The given will executors for @racket[register-finalizer]. The given
@ -366,6 +371,20 @@ debugging message also avoids the problem, since the finalization
procedure would then not close over @racket[b].)} procedure would then not close over @racket[b].)}
@deftogether[(
@defproc[(make-late-weak-box [v any/c]) weak-box?]
@defproc[(make-late-weak-hasheq [v any/c]) (and/c hash? hash-eq? hash-weak?)]
)]{
Like @racket[make-weak-box] and @racket[make-weak-hasheq], but with
``late'' weak references that last longer than references in the
result of @racket[make-weak-box] or @racket[make-weak-hasheq].
Specifically, a ``late'' weak reference remains intact if a value is
unreachable but not yet processed by a finalizer installed with
@racket[register-finalizer]. ``Late'' weak references are intended for
use by such finalizers.}
@defproc[(make-sized-byte-string [cptr cpointer?] [length exact-nonnegative-integer?]) @defproc[(make-sized-byte-string [cptr cpointer?] [length exact-nonnegative-integer?])
bytes?]{ bytes?]{