5.7 Custodian Shutdown Registration

► |  | The Racket Foreign Interface

1 | Overview
2 | Loading Foreign Libraries
3 | C Types
4 | Pointer Functions
5 | Derived Utilities
6 | Miscellaneous Support
7 | Unexported Primitive Functions
| Bibliography
| Index

▼ | 5 | Derived Utilities

5.1 | Safe Homogenous Vectors
5.2 | Safe C Vectors
5.3 | Tagged C Pointer Types
5.4 | Serializable C Struct Types
5.5 | Defining Bindings
5.6 | Allocation and Finalization
5.7 | Custodian Shutdown Registration
5.8 | Atomic Execution
5.9 | Speculatively Atomic Execution
5.10 | Thread Scheduling
5.11 | Ports
5.12 | Process-Wide and Place-Wide Registration
5.13 | Operating System Threads
5.14 | Garbage Collection Callbacks
5.15 | Objective-C FFI
5.16 | Cocoa Foundation
5.17 | COM (Common Object Model)
5.18 | File Security-Guard Checks
5.19 | Windows API Helpers

On this page:

register-custodian-shutdown
unregister-custodian-shutdown
register-finalizer-and-custodian-shutdown
make-custodian-at-root

top ← prev up next →

#### 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?]) |  | → |  | cpointer?
> v : any/c
> callback : (any/c . -> . any)
> custodian : custodian? = (current-custodian)
> at-exit? : any/c = #f
> weak? : 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 always weakly held by the custodian, even if weak? is #f; see scheme_add_managed for more information.

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 and 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. See also register-finalizer-and-custodian-shutdown.

> > 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? |
> > |  | #:weak? weak? |
> > |  | #:custodian-unavailable unavailable-callback]) |
> → any
> v : any/c
> callback : (any/c . -> . any)
> custodian : custodian? = (current-custodian)
> at-exit? : any/c = #f
> weak? : any/c = #f
> | 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.

If custodian is already shut down, then unavailable-callback is applied in tail position to a function that registers a finalizer. By default, a finalizer is registered anyway, but usually a better choice is to report an error. If custodian is not already shut down, then the result from register-finalizer-and-custodian-shutdown is #<void>.

Added in version 6.1.1.6 of package base.

> 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 ← prev up next →