14.7 Custodians (original) (raw)

14.7 Custodians🔗ℹ

See Custodians for basic information on the Racket custodian model.

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

Creates a new custodian that is subordinate to cust. Whencust 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.

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 removescust (and its subordinates) as managers of all threads; when a thread has no managers, it is killed (or suspended; seethread/suspend-to-kill) If the current thread is to be killed, all other shut-down actions take place before killing the thread.

If cust is already shut down, thencustodian-shutdown-all has no effect. When a custodian is shut down and it has subordinate custodians, the subordinates are not only shut down, they no longer count as subordinates.

Returns #t if cust has been shut down withcustodian-shutdown-all or if it was a subordinate of a custodian that is shut down, #f otherwise.

Added in version 6.11.0.5 of package base.

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.

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

If cust has been shut down, the result is '(). Ifcust was a subordinate of a custodian that was shut down, then it cannot be a subordinate of super.

Memory accounting is normally available, but not in the CGC implementation.

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

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

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

The stop-cust must be a subordinate custodian oflimit-cust.

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

If a check is registered, and if Racket later reaches a state after garbage collection (see Garbage Collection) wherelimit-cust owns more than limit-amt bytes, thenstop-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 forcustodian-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 tolimit-cust can be arbitrarily large, then stop-custmust be the same as limit-cust, so that excessively large immediate allocations can be rejected with anexn:fail:out-of-memory exception.

New memory allocation will be accounted to the runningthread’s managing custodian. In other words, a custodian’s limit applies only to the allocation made by the threads that it manages. See also call-in-nested-thread for a simpler setup.

Examples:

Non-examples:

Returns a custodian box that contains v as long ascust has not been shut down. If cust is already shut down, the custodian box’s value is immediately removed.

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.

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

Returns the value in the given custodian box, or #f if the value has been removed.