5.8 Custodian Shutdown Registration
(require ffi/unsafe/custodian) | package: base |
procedure
(register-custodian-shutdown v callback [ custodian #:at-exit? at-exit? #:weak? weak? #:ordered? ordered?]) → cpointer? v : any/c callback : (any/c . -> . any) custodian : custodian? = (current-custodian) at-exit? : any/c = #f weak? : any/c = #f ordered? : any/c = #f
If at-exit? is true, then callback is applied when Racket exits, even if the custodian is not explicitly shut down.
If weak? is true, then callback may not be called if v is determined to be unreachable during garbage collection. The value v is initially weakly held by the custodian, even if weak? is #f. A value associated with a custodian can therefore be finalized via will executors, at least through will registrations and register-finalizer uses after calling register-custodian-shutdown, but the value becomes strongly held when no there are no other strong references and no later-registered finalizers or wills apply.
If ordered? is true when weak is #f, then v is retained in a way that allows finalization of v via register-finalizer to proceed. For the CS implementation of Racket, v must not refer to itself or to a value that can refer back to v.
Normally, weak? should be false. To trigger actions based on
finalization or custodian shutdown—
Changed in version 7.8.0.8 of package base: Added the #:ordered? argument.
procedure
(unregister-custodian-shutdown v registration) → void? v : any/c registration : cpointer?
procedure
(register-finalizer-and-custodian-shutdown v callback [ custodian #:at-exit? at-exit? #:custodian-available available-callback #:custodian-unavailable unavailable-callback]) → any v : any/c callback : (any/c . -> . any) custodian : custodian? = (current-custodian) at-exit? : any/c = #f
available-callback : ((any/c . -> . void?) . -> . any) = (lambda (unreg) (void))
unavailable-callback : ((-> void?) . -> . any) = (lambda (reg-fnl) (reg-fnl))
When v is successfully registered with custodian and a finalizer is registered, then available-callback is called with a function unreg that unregisters the v and disables the use of callback through the custodian or a finalizer. The value v must be provided to unreg (otherwise it would be in unreg’s closure, possibly preventing the value from being finalized). The available-callback function is called in tail position, so its result is the result of register-finalizer-and-custodian-shutdown.
If custodian is already shut down, then unavailable-callback is applied in tail position to a function reg-fnl that registers a finalizer. By default, a finalizer is registered anyway, but usually a better choice is to report an error.
Added in version 6.1.1.6 of package base.
Changed in version 8.1.0.6: Added the #:custodian-available argument.
procedure
Creating a child of the root custodian is useful for registering a shutdown function that will be triggered only when the current place terminates.
Added in version 6.9.0.5 of package base.