#
Chapter 13
Memory Management

## 13.1 Weak Boxes

A weak box is similar to a normal box (see section 3.11), but when the automatic memory manager can prove that the content value of a weak box is only reachable via weak references, the content of the weak box is replaced with `#f`. A weak reference is a reference through a weak box, through a key reference in a weak hash table (see section 3.14), through a value in an ephemeron where the value can be replaced by `#f` (see section 13.2), or through a custodian (see section 9.2).

- `(make-weak-box``` `v``)` returns a new weak box that initially contains `v`.

- `(weak-box-value``` `weak-box``)` returns the value contained in `weak-box`. If the memory manager has proven that the previous content value of `weak-box` was reachable only through a weak reference, then `#f` is returned.

- `(weak-box?``` `v``)` returns `#t` if `v` is a weak box, `#f` otherwise.

## 13.2 Ephemerons

An ephemeron is similar to a weak box (see section 13.1), except that

1. an ephemeron contains a key and a value; the value can be extracted from the ephemeron, but the value is replaced by `#f` when the automatic memory manager can prove that either the ephemeron or the key is reachable only through weak references (see section 13.1); and

2. nothing reachable from the value in an ephemeron counts toward the reachability of an ephemeron key (whether for the same ephemeron or another), unless the same value is reachable through a non-weak reference, or unless the value's ephemeron key is reachable through a non-weak reference (see section 13.1 for information on weak references).

In particular, an ephemeron can be combined with a weak hash table (see section 3.14) to produce a mapping where the memory manager can reclaim key-value pairs even when the value refers to the key. An example is shown below.

- `(make-ephemeron``` `key-v v``)` returns a new ephemeron whose key is `key-v` and whose value is initially `v`.

- `(ephemeron-value``` `ephemeron``)` returns the value contained in `ephemeron`. If the memory manager has proven that the key for `ephemeron` is only weakly reachable, then the result is `#f`.

- `(ephemeron?``` `v``)` returns `#t` if `v` is an ephemeron, `#f` otherwise.

Example:

    ;; This weak map is like a weak hash table, but
    ;;  without the key-in-value problem:
    (define (make-weak-map)
      (make-hash-table 'weak))
    SPACE
    (define (weak-map-put! m k v)
      (hash-table-put! m k (make-ephemeron k (box v))))
    SPACE
    (define (weak-map-get m k def-v)
      (let ([v (hash-table-get m k (lambda () #f))])
        (if v
            (let ([v (ephemeron-value v)])
              (if v
                  (unbox v)
                  def-v))
            def-v)))
    SPACE
    (define m (make-weak-map))
    (define k (list 1 2))
    (weak-map-put! m k k)
    (weak-map-get m k #f) ; => '(1 2)
    (set! k #f)
     list is eventually GCed even if m remains reachable

## 13.3 Will Executors

A will executor manages a collection of values and associated will procedures. The will procedure for each value is ready to be executed when the value has been proven (by the automatic memory manager) to be unreachable, except through weak references (see section 13.1) or as the registrant for other will executors. A will is useful for triggering clean-up actions on data associated with an unreachable value, such as closing a port embedded in an object when the object is no longer used.

Calling the ``will-execute`` or ``will-try-execute`` procedure executes a will that is ready in the specified will executor. Wills are not executed automatically, because certain programs need control to avoid race conditions. However, a program can create a thread whose sole job is to execute wills for a particular executor.

- `(make-will-executor``)` returns a new will executor with no managed values.

- `(will-executor?``` `v``)` returns `#t` if `v` is a will executor, `#f` otherwise.

- `(will-register``` `executor v proc``)` registers the value `v` with the will procedure `proc` in the will executor `executor`. When `v` is proven unreachable, then the procedure `proc` is ready to be called with `v` as its argument via ``will-execute`` or ``will-try-execute``. The `proc` argument is strongly referenced until the will procedure is executed.

- `(will-execute``` `executor``)` invokes the will procedure for a single ``unreachable'' value registered with the executor `executable`. The value(s) returned by the will procedure is the result of the ``will-execute`` call. If no will is ready for immediate execution, ``will-execute`` blocks until one is ready.

- `(will-try-execute``` `executor``)` is like ``will-execute`` if a will is ready for immediate execution. Otherwise, `#f` is returned.

If a value is registered with multiple wills (in one or multiple executors), the wills are readied in the reverse order of registration. Since readying a will procedure makes the value reachable again, the will must be executed and the value must be proven again unreachable through only weak references before another of the wills is readied or executed. However, wills for distinct unreachable values are readied at the same time, regardless of whether the values are reachable from each other.

A will executor's register is held non-weakly until after the corresponding will procedure is executed. Thus, if the content value of a weak box (see section 13.1) is registered with a will executor, the weak box's content is not changed to `#f` until all wills have been executed for the value and the value has been proven again reachable through only weak references.

## 13.4 Garbage Collection

`(collect-garbage``)` forces an immediate garbage collection. Since MzScheme uses a ``conservative'' garbage collector, some effectively unreachable data may remain uncollected (because the collector cannot prove that it is unreachable). This procedure provides some control over the timing of collections, but garbage will obviously be collected even if this procedure is never called.

`(current-memory-use``` [`custodian`]`)` returns an estimate of the number of bytes of memory occupied by reachable data from `custodian`. (The estimate is calculated without performing an immediate garbage collection; performing a collection generally decreases the number returned by ``current-memory-use``.) If `custodian` is not provided, the estimate is a total reachable from any custodians. Unless MzScheme is compiled with special support for memory accounting, the estimate is the same (i.e., all memory) for any individual custodian.

`(dump-memory-stats``)` dumps information about memory usage to the (low-level) standard output port.