diff --git a/pkgs/racket-doc/scribblings/foreign/pointers.scrbl b/pkgs/racket-doc/scribblings/foreign/pointers.scrbl index 83f5419b5e..3723b7d314 100644 --- a/pkgs/racket-doc/scribblings/foreign/pointers.scrbl +++ b/pkgs/racket-doc/scribblings/foreign/pointers.scrbl @@ -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?]{ Registers a finalizer procedure @racket[finalizer-proc] with the given -@racket[obj], which can be any Racket (GC-able) object. The finalizer -is registered with a will executor; see -@racket[make-will-executor]. The finalizer is invoked when -@racket[obj] is about to be collected. +@racket[obj], which can be any Racket (GC-able) object. The finalizer +is registered with a ``late'' @tech[#:doc reference.scrbl]{will +executor} that makes wills ready for a value only after all +@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 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].)} +@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?]) bytes?]{