FunctionPackage: exclToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 10.0
New since the initial 10.0 release.

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:

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:

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.

ToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 10.0
New since the initial 10.0 release.