►The Racket Foreign Interface
▼5 Derived Utilities
On this page:
register-custodian-shutdown
unregister-custodian-shutdown
register-finalizer-and-custodian-shutdown
make-custodian-at-root
  top  contents    up   

5.7 Custodian Shutdown Registration

 (require ffi/unsafe/custodian) package: base
The ffi/unsafe/custodian library provides utilities for registering shutdown callbacks with custodians.

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
Registers callback to be applied (in atomic mode and an unspecified Racket thread) to v when custodian is shutdown. If custodian is already shut down, the result is #f and v is not registered. Otherwise, the result is a pointer that can be supplied to unregister-custodian-shutdown to remove the registration.

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—whichever happens first—leave weak? as #f and have a finalizer run in atomic mode to check that the custodian shutdown has not happened and then cancel the shutdown action via unregister-custodian-shutdown. If weak? is true or if the finalizer is not run in atomic mode, then there’s no guarantee that either of the custodian or finalizer callbacks has completed by the time that the custodian shutdown has completed; v might be no longer registered to the custodian, while the finalizer for v might be still running or merely queued to run. Furthermore, if finalization is via register-finalizer (as opposed to a will executor), then supply ordered? as true; if ordered? is false while weak? is false, then custodian may retain v in a way that does not allow finalization to be triggered when v is otherwise inaccessible. See also register-finalizer-and-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?
Cancels a custodian-shutdown registration, where registration is a previous result from register-custodian-shutdown applied to v. If registration is #f, then no action is taken.

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))
Registers callback to be applied (in atomic mode) to v when custodian is shutdown or when v is about to be collected by the garbage collector, whichever happens first. The callback is only applied to v once. The object v is subject to the the constraints of register-finalizer—particularly the constraint that v must not be reachable from itself.

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

(make-custodian-at-root) → custodian?

Creates a custodian that is a child of the root custodian, bypassing the current-custodian setting.

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.

  top  contents    up