(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 220.127.116.11 of package base: Added the #:ordered? argument.
(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 18.104.22.168 of package base.
Changed in version 22.214.171.124: Added the #:custodian-available argument.
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 126.96.36.199 of package base.