# The WeakRef interface

Most Modula-3 programs simply let the garbage collector deallocate storage automatically, but some programs need more control. For example, if a variable allocated in the traced heap contains a handle on a resource in the operating system or in some other address space, then when the variable is garbage-collected it may be important to deallocate the resource. The `WeakRef` interface provides this additional control. weak reference

deallocating resources

garbage collection weak references

A node is a datum allocated on the traced heap. Thus a node is either the referent of a variable of a fixed reference type or the data record of a traced object. Note that a node is not a Modula-3 reference, but the allocated storage to which a reference can refer.

A `WeakRef.T` is a data structure that refers to a node without protecting the node from the garbage collector. If `w` is a weak reference, we write `nd(w)` to denote the node to which `w` refers.

We say that a weak reference `w` dies at the moment that the garbage collector detects that `nd(w)` is unreachable. A precise definition of unreachable is given below. Once a weak reference has died, it remains dead forever, even if the node to which it refers becomes reachable again.

Associated with each weak reference `w` is a cleanup procedure `cp(w)`. If the cleanup procedure is not `NIL`, the garbage collector will schedule a call to it when the weak reference dies.

    INTERFACE WeakRef;

    TYPE T =
      RECORD
        byte: ARRAY [0..7] OF BITS 8 FOR [0..255]
      END;

Please treat this as though it were an opaque type: the only operations allowed are assignment, equality tests, and the procedures in this interface.

    PROCEDURE FromRef(r: REFANY; p: CleanUpProc := NIL): T;

Return a weak reference `w` such that `nd(w) = r` and `cp(w) = p`. It is a checked runtime error if `r` is `NIL`. It is illegal to create more than one weak reference with a non-nil cleanup to the same node; violations of this rule may lead to a checked runtime error, or may cause one of the cleanup actions to be omitted. `FromRef` is not necessarily functional: it is possible that `nd(w1) = nd(w2)` but `w1 # w2`.

    PROCEDURE ToRef(w: T): REFANY;

Return a reference to `nd(w)`, unless `w` is dead, in which case return `NIL`.

    TYPE CleanUpProc = PROCEDURE(READONLY w: T; r: REFANY);

If `cp(w)` is not `NIL`, then when `w` dies, the garbage collector will schedule the call `cp(w)(w, <reference to nd(w)>)`.

    END WeakRef.

The cleanup procedure will be executed at some point after the weak reference dies. A cleanup procedure is called with no locks held; it must return promptly to allow other objects to be cleaned up.

The computation `cp(w)(w, ref)` is allowed to store `ref` in a non-local variable, thus making `nd(w)` reachable again; the heap storage will not have been freed. This does not change the fact that `w` is dead. The cleanup procedure can re-enable cleanup, if desired, by creating a new weak reference to `nd(w)`.

The storage for a node is reclaimed when it is unreachable and all weak references to it are dead and all cleanup calls scheduled for it have been completed.

Finally we come to the precise definition of ``reachable'':

A node is reachable if it can be reached by a path of traced references starting from a current procedure activation record, a global variable, or a weakly referenced node with a non-nil cleanup other than itself.

Thus a weak reference to a node `nd` does not make `nd` reachable, but if it has a non-nil cleanup, it makes other nodes referenced from `nd` reachable.

For example, if `A` and `B` are two nodes that are weakly referenced by weak references with non-nil cleanup procedures, then if `B` is reachable from `A`, then `B` is reachable. But if `A` is not reachable, then the garbage collector will eventually detect this and schedule the cleanup of `A`. If the cleanup call returns without resurrecting `A`, then `A`'s storage will be reclaimed, at which point `B` will be unreachable, which will lead to its cleanup.

If `A` and `B` are weakly referenced nodes with non-nil cleanups that are connected by a cycle of traced references, then both of them are reachable. As long as the cycle persists, neither will be cleaned up. This situation represents a storage leak and should be avoided.

## Examples

1. Suppose you want writers of the class `WrX.T` to be automatically flushed and closed if they become unreachable. Then you could write code like the following in the `WrX` module:

        MODULE WrX; IMPORT WeakRef, Wr, ...;

        PROCEDURE New(...): T =
          VAR res := NEW(T); BEGIN
            (* ... initialize res as a WrX.T ... *)
            EVAL WeakRef.FromRef(res, Cleanup);
            RETURN res
          END New;

        PROCEDURE Cleanup(READONLY self: WeakRef.T; ref: REFANY) =
          VAR wr: T := ref; BEGIN
            IF NOT Wr.Closed(wr) THEN
              Wr.Flush(wr);
              Wr.Close(wr)
            END
          END Cleanup;

   There is no danger that another thread could close the writer after the test `NOT Wr.Closed(wr)` and before the call `Wr.Flush(wr)`, since when `Cleanup` is called, the writer is unreachable. Therefore the cleanup method has exclusive access to the writer.

2. The network object runtime must map wire representations for network objects into surrogate objects. To hand out the same surrogate for the same wire representation, it keeps a table mapping wire representations to surrogates. This table contains weak references, so the table entry itself does not prevent the surrogate from being collected. When the surrogate is collected, it is removed from the table and the server containing that object is notified that the client no longer has a surrogate for it.

   When a weak reference in the table becomes dead, the network object represented by the dead surrogate might be unmarshaled by the address space before the surrogate is cleaned up. In this case the unmarshaling code resurrects the unreachable surrogate by creating a new weak reference and inserting it in the table in place of the dead weak reference. The cleanup code can tell whether to report in clean by checking whether there is a new weak reference in the table or not.

   Here is a sketch of the code:

        TYPE Surrogate = OBJECT wr: WireRep; ... END;

        VAR
          mu := NEW(MUTEX);
          <* LL >= {mu} *>
          tbl := NEW(WireRepToWeakRefTbl.T);

   The mutex `mu` must be held to read or write `tbl` (that is what the `LL` pragma means).

   The table `tbl` maps `WireRep`s to `WeakRef`s that reference surrogates.

   The following invariants hold whenever `mu` is not held:

   If `tbl(wrep)` is not dead, then `nd(tbl(wrep))` is the surrogate for the network object whose wire representation is `wrep`.

   If `tbl(wrep)` is dead, then the surrogate for `wrep` is unreachable.

   If `tbl` has no entry for `wrep`, then the address space contains no surrogate for `wrep`.

        PROCEDURE Cleanup(READONLY wref: WeakRef.T; ref: REFANY) =
        <* LL = {} *>
          VAR
            srg := NARROW(ref, Surrogate);
            tblVal: WeakRef.T;
          BEGIN
            LOCK mu DO
              IF tbl.get(srg.wr, tblVal) AND wref = tblVal
              THEN
                EVAL tbl.delete(srg.wr);
                ... Report that srg is deleted ...
              END
            END
          END Cleanup;

        PROCEDURE WireRepToSrg(wrep: WireRep): Surrogate =
          VAR wref: WeakRef.T; res: Surrogate; BEGIN
            LOCK mu DO
              IF tbl.get(wrep, wref) THEN
                res := WeakRef.ToRef(wref);
                IF res # NIL THEN RETURN res END
              END;
              res := NewSurrogate(wrep);
              EVAL tbl.put(wrep, WeakRef.FromRef(res, Cleanup));
              RETURN res
            END
          END WireRepToSrg;

   In the above we assume that `NewSurrogate` creates a new surrogate from a wire representation.