See Custodians for basic information on the Racket custodian model.
cust : (and/c custodian? (not/c custodian-shut-down?)) = (current-custodian)
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.
If cust is already shut down, then custodian-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.
Added in version 188.8.131.52 of package base.
If cust has been shut down, the result is '(). If cust 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.
(custodian-require-memory limit-cust need-amt stop-cust) → void? limit-cust : custodian? need-amt : exact-nonnegative-integer? stop-cust : custodian?
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.
The stop-cust must be a subordinate custodian of limit-cust.
(custodian-limit-memory limit-cust limit-amt [ stop-cust]) → void? limit-cust : custodian? limit-amt : exact-nonnegative-integer? stop-cust : custodian? = limit-cust
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.
New memory allocation will be accounted to the running thread’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.
> (require racket/async-channel) > (define ch (make-async-channel))
> (parameterize ([current-custodian (make-custodian)]) (thread-wait (thread (λ () (with-handlers ([exn:fail:out-of-memory? (λ (e) (async-channel-put ch e))]) (custodian-limit-memory (current-custodian) (* 1024 1024)) (make-bytes (* 4 1024 1024)) (async-channel-put ch "Not OK"))))) (async-channel-get ch))
(exn:fail:out-of-memory "out of memory" #<continuation-mark-set>)
> (define cust (make-custodian))
> (with-handlers ([exn:fail:out-of-memory? (λ (e) (error "Caught OOM exn"))]) (call-in-nested-thread (λ () (custodian-limit-memory cust (* 1024 1024)) (make-bytes (* 4 1024 1024)) "Not OK") cust))
Caught OOM exn
> (parameterize ([current-custodian (make-custodian)]) (custodian-limit-memory (current-custodian) (* 1024 1024)) ; Allocation of make-bytes is charged to the current thread’s ; managing custodian, not the new custodian. (make-bytes (* 4 1024 1024)) "Not OK")