16.1 Custodians🔗ℹ

A custodian manages objects such as threads, file-stream ports, network connections, and other custodians. Whenever a thread, etc., is created, it is placed under the management of the current custodian as determined by the Custodian.current parameter.

A custodian box created with Custodian.Box strongly holds onto a value placed in the box until the box’s custodian is shut down.

A new custodian is always created with some existing custodian as its parent. If the parent custodian is shut down, then the child is shut down, too.

The Custodian.is_shutdown method reports whether a custodian has been shut down already. A custodian that has been shut down cannot become the owner of new objects.

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.

The Custodian.limit_memory method registers a limited-memory check. If Rhombus later reaches a state after garbage collection (see Garbage Collection) where cust owns more than limit_amt bytes, then shutdown_cust is shut down.

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.

For reliable shutdown, limit_amt 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 shutdown_cust must be the same as cust, so that excessively large immediate allocations can be rejected with an Exn: Fail: OutOfMemory exception.