get-references

Arguments: object &optional include-stacks

This function accepts an object and returns a heapwalker vector filled with all objects in the lisp heap or in lispstatic space which point directly to the given object. Objects are usually found using get-objects.

A heapwalk vector is a simple vector of type t whose first element is the number of objects of which were found, whose next elements are the objects found, and whose last elements are unspecified (the vector is made somewhat bigger than is necessary). Thus suppose 32 objects referencing object were found. The returned vector will have 32 as its first element, then elements 1 through 33 will be those 32 objects. The vector may have length larger than 33, and the remaining elements, if any, are unspecified.

Note that compound structures might not point to the object directly; for example, if a list has an element within it, the first call to get-references will return only the cons cell whose car is that object; you would have to repeat the get-references on that cons cell to find the cons whose cdr points to it, and so on backward through the list until you find a recognizable structure, symbol, or function that points to the head of the list.

If you call this function interactively then the special variable * tends to show up in the results quite often, because it is changing every time to point to the heapwalker vector result. On the other hand, the result is pretty printed in the listener, and usually you can see the first value in the most recent result. A useful paradigm once you have called get-references the first time is

 (excl::get-references (aref * 1))

which can be repeated to chain backwards through the oldest link to the original object, though sometimes you might want to index a different item, depending on what looks interesting. You may also have to scroll back up the screen, so be sure to do this in a window that can scroll quite a bit (such as an emacs buffer), since the heapwalker vectors will tend to get long after a few iterations.

Note the following:

• Do a (gc t) -- that is, a global gc -- before you start using this tool. Heapwalkers don't care if an object is dead or not, so it may be that you are grabbing objects from the heap which would have otherwise been collected because it was dead.
• *, **, and *** are assigned results from previous invocations of get-references, so it is likely that one of them will be in the next result vector.

The include-stacks argument

The include-stacks argument expands the search for stack objects, providing reasonable results for stack locations. Under the normal rules of get-references, an object seen in a stack location would result in the stack itself being seen in the heapwalker results vector. But because stacks are hard to identify, depending on whether the scheduler is turned on, and also depending on whether virtual threads, os-threads, or smp is impemented, and so the include-stacks options choose to look at stacks on a per-frame basis. Frames are identified by frame-descriptor structs, and are unique per thread. A frame-descriptor might be valid (because its invocation is still dynamically in scope), or invalid (because its execution has terminated). If the frame-descriptor is valid, it can be queried by one of the debugger-api functions (see debugger-api.htm, or simply by performing debugger commands such as :zoom and :local when the frame-descriptor is found.

Whenever a frame-descriptor is seen in a results vector due to the include-stacks argument options, it may be necessary to use the new :r option to the :local command to see the raw data - a much expanded view that includes slots of stack-allocated objects. Note that there is no distinction made between a frame-descriptor whose frame has a slot with the object in it and a frame-descriptor which as a lisp struct actually references the object.

The possible values for include-stacks are:

• t: besides heap objects which reference the object argument, any frame which holds the object will have its frame-desriptor added to the result vector.
• :only: same as t, but only those objects which are on the stack and not referenced in the heap will be captured. This is slightly different than other get-references results; the object argument is ignored, and all objects meeting the criterion are placed into the result vector (and not any objects that reference those objects). This might provide a set of objects from which to initiate further get-references calls. This option reveals any truly transient data, but beware: when a result vector has captured such an object it is no longer transient, since it is now also referenced by a lisp object (the now-older results vector).
• :all: same as :only, but an object meets the criterion even if it is referenced by a heap object. The only criterion for an object to be in the results vector with :all is that it be referenced on a stack somewhere.
• nil (the default): stacks are not searched at all - only the heap is searched.

See Heap walkers in Allegro CL for more information.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page is new in the 10.0 release.
Created 2019.8.20.