13.7 Custodians

► |  | The Racket Reference

1 | Language Model
2 | Syntactic Forms
3 | Datatypes
4 | Structures
5 | Classes and Objects
6 | Units
7 | Contracts
8 | Pattern Matching
9 | Control Flow
10 | Concurrency and Parallelism
11 | Macros
12 | Input and Output
13 | Reflection and Security
14 | Operating System
15 | Memory Management
16 | Unsafe Operations
17 | Running Racket
| Bibliography
| Index

▼ | 13 | Reflection and Security

13.1 | Namespaces
13.2 | Evaluation and Compilation
13.3 | The racket/ load Language
13.4 | Module Names and Loading
13.5 | Impersonators and Chaperones
13.6 | Security Guards
13.7 | Custodians
13.8 | Thread Groups
13.9 | Structure Inspectors
13.10 | Code Inspectors
13.11 | Sandboxed Evaluation

On this page:

custodian?
make-custodian
custodian-shutdown-all
current-custodian
custodian-managed-list
custodian-memory-accounting-available?
custodian-require-memory
custodian-limit-memory
make-custodian-box
custodian-box?
custodian-box-value

top ← prev up next →

#### 13.7`` Custodians

See Custodians for basic information on the Racket custodian model.

> procedure (custodian? v) → boolean?
> v : any/c

Returns #t if v is a custodian value, #f otherwise.

> procedure (make-custodian [cust]) → custodian?
> cust : custodian? = (current-custodian)

Creates a new custodian that is subordinate to cust. When cust is directed (via custodian-shutdown-all) to shut down all of its managed values, the new subordinate custodian is automatically directed to shut down its managed values as well.

> procedure (custodian-shutdown-all cust) → void?
> cust : custodian?

> > > In GRacket, eventspaces managed by cust are also shut down.

Closes all file-stream ports, TCP ports, TCP listeners, and UDP sockets that are managed by cust (and its subordinates), and empties all custodian boxes associated with cust (and its subordinates). It also removes cust (and its subordinates) as managers of all threads; when a thread has no managers, it is killed (or suspended; see thread/suspend-to-kill) If the current thread is to be killed, all other shut-down actions take place before killing the thread.

> parameter (current-custodian) → custodian?
> (current-custodian cust) → void?
> cust : custodian?

> > > In GRacket, custodians also manage eventspaces.

A parameter that determines a custodian that assumes responsibility for newly created threads, file-stream ports, TCP ports, TCP listeners, UDP sockets, and byte converters.

> procedure (custodian-managed-list cust super) → list?
> cust : custodian?
> super : custodian?

Returns a list of immediately managed objects (not including custodian boxes) and subordinate custodians for cust, where cust is itself subordinate to super (directly or indirectly). If cust is not strictly subordinate to super, the exn:fail:contract exception is raised.

> procedure (custodian-memory-accounting-available?) → boolean?

> > > Memory accounting is normally available in Racket 3m, which is the main variant of Racket, and not normally available in Racket CGC.

Returns #t if Racket is compiled with support for per-custodian memory accounting, #f otherwise.

> > procedure
> > (custodian-require-memory |  | limit-cust |  |  |  |
> > |  | need-amt |  |  |  |
> > |  | stop-cust) |  | → |  | void?
> limit-cust : custodian?
> need-amt : exact-nonnegative-integer?
> stop-cust : custodian?

Registers a required-memory check if Racket is compiled with support for per-custodian memory accounting, otherwise the exn:fail:unsupported exception is raised.

If a check is registered, and if Racket later reaches a state after garbage collection (see Garbage Collection) where allocating need-amt bytes charged to limit-cust would fail or trigger some shutdown, then stop-cust is shut down.

> > procedure
> > (custodian-limit-memory |  | limit-cust |  |  |  |
> > |  | limit-amt |  |  |  |
> > | [ | stop-cust]) |  | → |  | void?
> limit-cust : custodian?
> limit-amt : exact-nonnegative-integer?
> stop-cust : custodian? = limit-cust

Registers a limited-memory check if Racket is compiled with support for per-custodian memory accounting, otherwise the exn:fail:unsupported exception is raised.

If a check is registered, and if Racket later reaches a state after garbage collection (see Garbage Collection) where limit-cust owns more than limit-amt bytes, then stop-cust is shut down.

> > > A custodian’s limit is checked only after a garbage collection, except that it may also be checked during certain large allocations that are individually larger than the custodian’s limit. A single garbage collection may shut down multiple custodians, even if shutting down only one of the custodians would have reduced memory use for other custodians.

For reliable shutdown, limit-amt for custodian-limit-memory must be much lower than the total amount of memory available (minus the size of memory that is potentially used and not charged to limit-cust). Moreover, if individual allocations that are initially charged to limit-cust can be arbitrarily large, then stop-cust must be the same as limit-cust, so that excessively large immediate allocations can be rejected with an exn:fail:out-of-memory exception.

> procedure (make-custodian-box cust v) → custodian-box?
> cust : custodian?
> v : any/c

Returns a custodian box that contains v as long as cust has not been shut down.

A custodian box is a synchronizable event (see Events). The custodian box becomes ready when its custodian is shut down; the synchronization result of a custodian box is the custodian box itself.

> procedure (custodian-box? v) → boolean?
> v : any/c

Returns #t if v is a custodian box produced by make-custodian-box, #f otherwise.

> procedure (custodian-box-value cb) → any
> cb : custodian-box?

Returns the value in the given custodian box, or #f if the value has been removed.
top ← prev up next →