sbcl.sbcl/contrib/sb-introspect/sb-introspect.texinfo

@c Generated by the sb-manual contrib. Do not edit.

@node sb introspect
@section sb-introspect

@menu
* Finding Definitions: finding definitions.
* Special Variables: sb introspect variables.
* Functions: sb introspect functions.
* Types and Classes: sb introspect types.
* Allocation: sb introspect allocation.
@end menu

The @code{sb-introspect} module is about finding definitions, as well
as querying their properties and relationships in the running image.

@node finding definitions
@subsection Finding Definitions

@anchor{Structure sb-introspect definition-source}
@ttindex @sortas{definition-source sb-introspect} definition-source [sb-introspect]
@deffn{Structure} sb-introspect:definition-source
This structure identifies a sexp in a compiled file.
Despite the name, the source location may not correspond to a
definition but to e.g. a function call (see @code{who-calls}).
@end deffn
@anchor{Function sb-introspect definition-source-pathname}
@ffindex @sortas{definition-source-pathname sb-introspect} definition-source-pathname [sb-introspect]
@deffn{Function} sb-introspect:definition-source-pathname instance
Pathname of the source file.
This is @code{nil} if the source location is not in a compiled file.
@end deffn
@anchor{Function sb-introspect definition-source-form-path}
@ffindex @sortas{definition-source-form-path sb-introspect} definition-source-form-path [sb-introspect]
@deffn{Function} sb-introspect:definition-source-form-path instance
List of indices that identify the sexp in the
file given by @code{definition-source-pathname}. The first element in the
list is the index of the top-level form that contains the sexp. If the
file was compiled at a high enough debug level, then the rest of the
elements recursively index into the list structure of the top-level
form.

Thus, the form path is somewhat stable regarding edits in the file,
but it gets invalidated by, for example, inserting a new top-level
form before the sexp in question.
@end deffn
@anchor{Function sb-introspect definition-source-form-number}
@ffindex @sortas{definition-source-form-number sb-introspect} definition-source-form-number [sb-introspect]
@deffn{Function} sb-introspect:definition-source-form-number instance
Depth-first index of the sexp within the top-level
form identified by the first element of @code{definition-source-form-path}.
That is, this is the index of the sexp in the list of subexpressions
of the top-level form ordered according to depth-first traversal. 0
corresponds to the top-level form itself.

When combined with the index of the top-level form (given by the first
element of @code{definition-source-form-path}), the form number allows
reconstruction of the rest of the form path, which may be missing.
This requires parsing the source file. Currently, this job is
delegated to e.g. SLIME.
@end deffn
@anchor{Function sb-introspect definition-source-character-offset}
@ffindex @sortas{definition-source-character-offset sb-introspect} definition-source-character-offset [sb-introspect]
@deffn{Function} sb-introspect:definition-source-character-offset instance
Character offset of the top-level form containing
the sexp.
@end deffn
@anchor{Function sb-introspect definition-source-file-write-date}
@ffindex @sortas{definition-source-file-write-date sb-introspect} definition-source-file-write-date [sb-introspect]
@deffn{Function} sb-introspect:definition-source-file-write-date instance
@code{file-write-date} of @code{definition-source-pathname} at
the time of compilation. @code{nil} if not compiled from a file.
@end deffn
@anchor{Function sb-introspect definition-source-plist}
@ffindex @sortas{definition-source-plist sb-introspect} definition-source-plist [sb-introspect]
@deffn{Function} sb-introspect:definition-source-plist instance
The @code{source-plist} from @code{with-compilation-unit} in effect
when the file was compiled.
@end deffn
@anchor{Function sb-introspect find-definition-source}
@ffindex @sortas{find-definition-source sb-introspect} find-definition-source [sb-introspect]
@deffn{Function} sb-introspect:find-definition-source object
Return the @code{definition-source} corresponding to the definition of @code{object}
or @code{nil} if there is no corresponding definition. @code{object} must be a
@code{package}, @code{function}, @code{method}, @code{method-combination}, @code{sb-mop:slot-definition},
@code{standard-object}, @code{structure-object}, @code{condition}, @code{class}, @code{structure-class},
or a subclass of @code{condition}. An error is signalled for other types.

A @code{definition-source} object is always returned for definitions that
exist, but the source location (e.g. @code{definition-source-pathname}) may
be missing.

For definitions that do not define an object (e.g. @code{defvar}), use
@code{find-definition-sources-by-name}.
@end deffn
@anchor{Function sb-introspect find-definition-sources-by-name}
@ffindex @sortas{find-definition-sources-by-name sb-introspect} find-definition-sources-by-name [sb-introspect]
@deffn{Function} sb-introspect:find-definition-sources-by-name name type
Returns a list of @code{definition-source}s for definitions of @code{name} with
the given definition @code{type}. A @code{definition-source} object is always
returned for definitions that exist, but the source location (e.g.
@code{definition-source-pathname}) may be missing. @code{type} can currently be one
of the following.

@itemize
@item Public definition types:

@code{:class}
@code{:compiler-macro}
@code{:condition}
@code{:constant}
@code{:function}
@code{:generic-function}
@code{:macro}
@code{:method}
@code{:method-combination}
@code{:package}
@code{:setf-expander}
@code{:structure}
@code{:symbol-macro}
@code{:type}
@code{:alien-type}
@code{:alien-callback}
@code{:variable}
@code{:declaration}

@item Internal definition types:

@code{:optimizer}
@code{:source-transform}
@code{:transform}
@code{:vop}
@code{:ir1-convert}
@end itemize

Definition types are disjoint. For example, @code{:type} refers to @code{deftype}s
but not @code{class}es or @code{sb-alien:define-alien-type}, as those are of
definition type @code{:class} and @code{:alien-type}, respectively. @code{:function} does
not include @code{:generic-function}, @code{:class} does not include @code{:structure},
etc. @code{:variable} refers to non-constant dynamic variables (e.g. those
defined with @code{defvar}, @code{defparameter}, @code{sb-ext:defglobal} or
@code{sb-alien:define-alien-variable} but not with @code{defconstant}).

Valid @code{name}s are generally @code{symbol}s with the following exceptions:

@itemize
@item For @code{:compiler-macro}, @code{:function}, @code{:generic-function} and @code{:method},
  anything that's @code{valid-function-name-p} is valid.

@item For @code{:package}, string designators are valid.
@end itemize

If an unsupported @code{type} is requested or @code{name} is invalid, this function
returns @code{nil}.
@end deffn
@node sb introspect variables
@subsection Special Variables

@anchor{Function sb-introspect who-binds}
@ffindex @sortas{who-binds sb-introspect} who-binds [sb-introspect]
@deffn{Function} sb-introspect:who-binds symbol
Find the source locations where the special variable @code{symbol} is bound,
and return them as an alist of function or macro name,
@code{definition-source} pairs.
@end deffn
@anchor{Function sb-introspect who-references}
@ffindex @sortas{who-references sb-introspect} who-references [sb-introspect]
@deffn{Function} sb-introspect:who-references symbol
Find the source locations where the special variable @code{symbol} is read,
and return them as an alist of function or macro name,
@code{definition-source} pairs.
@end deffn
@anchor{Function sb-introspect who-sets}
@ffindex @sortas{who-sets sb-introspect} who-sets [sb-introspect]
@deffn{Function} sb-introspect:who-sets symbol
Find the source locations where the special variable @code{symbol} is set,
and return them as an alist of function or macro name,
@code{definition-source} pairs.
@end deffn
@node sb introspect functions
@subsection Functions

@anchor{Function sb-introspect function-lambda-list}
@ffindex @sortas{function-lambda-list sb-introspect} function-lambda-list [sb-introspect]
@deffn{Function} sb-introspect:function-lambda-list function
Return the lambda list of @code{function}.
@code{function} must be a function object or a function name in the sense of
@code{valid-function-name-p}. Works for special operators, macros, simple
functions, interpreted functions, and generic functions.

The second return value indicates whether the lambda list could not be
determined (e.g. because the function was compiled with @code{debug} 0).
@end deffn
@anchor{Function sb-introspect function-type}
@ffindex @sortas{function-type sb-introspect} function-type [sb-introspect]
@deffn{Function} sb-introspect:function-type function-designator
Returns the ftype of @code{function-designator} or @code{nil}.
@end deffn
@anchor{Function sb-introspect method-combination-lambda-list}
@ffindex @sortas{method-combination-lambda-list sb-introspect} method-combination-lambda-list [sb-introspect]
@deffn{Function} sb-introspect:method-combination-lambda-list method-combination
Return the lambda list of the @code{method-combination} designator.
@code{method-combination} can be a method combination object,
or a method combination name.
@end deffn
@anchor{Function sb-introspect valid-function-name-p}
@ffindex @sortas{valid-function-name-p sb-introspect} valid-function-name-p [sb-introspect]
@deffn{Function} sb-introspect:valid-function-name-p name
See if @code{name} is a valid function name. In addition to the ANSI
definition of function name, which is symbols plus lists like (@code{setf}
@code{symbol}), SBCL allows (@code{sb-ext:cas} @code{symbol}) and various internal
constructs.
@end deffn
@anchor{Function sb-introspect find-function-callers}
@ffindex @sortas{find-function-callers sb-introspect} find-function-callers [sb-introspect]
@deffn{Function} sb-introspect:find-function-callers function &optional spaces
List functions that call @code{function} by searching @code{spaces} for code objects.
This can make previously garbage objects live.

@code{spaces} should be a list of the symbols @code{:dynamic}, @code{:static}, @code{:read-only},
or @code{:immobile} on @code{#+immobile-space}. The shorthand (@code{:all}) is also
accepted.
@end deffn
@anchor{Function sb-introspect find-function-callees}
@ffindex @sortas{find-function-callees sb-introspect} find-function-callees [sb-introspect]
@deffn{Function} sb-introspect:find-function-callees function
Return functions called by @code{function}.
@end deffn
@anchor{Function sb-introspect who-calls}
@ffindex @sortas{who-calls sb-introspect} who-calls [sb-introspect]
@deffn{Function} sb-introspect:who-calls function-name
Find the source locations where the global function @code{function-name} is
called, and return them as an alist of function or macro name,
@code{definition-source} pairs.
@end deffn
@anchor{Function sb-introspect who-macroexpands}
@ffindex @sortas{who-macroexpands sb-introspect} who-macroexpands [sb-introspect]
@deffn{Function} sb-introspect:who-macroexpands macro-name
Find the source locations where the macro @code{macro-name} is expanded, and
return them as an alist of function or macro name, @code{definition-source}
pairs.
@end deffn
@node sb introspect types
@subsection Types and Classes

@anchor{Function sb-introspect deftype-lambda-list}
@ffindex @sortas{deftype-lambda-list sb-introspect} deftype-lambda-list [sb-introspect]
@deffn{Function} sb-introspect:deftype-lambda-list type-specifier-name
Returns the lambda list of @code{type-specifier-name} as the first return
value, and a flag whether the arglist could be found as the second
value.

@code{type-specifier-name} must be a symbol. This function can find the
lambda list of derived type specifiers (e.g. those defined with
@code{deftype}) and classes with compound type specifier syntaxes (e.g. the
class @code{float}). It returns @code{nil}, @code{nil} for other type specifiers (e.g. @code{and},
@code{or}, @code{not}) and types (e.g. @code{list}).
@end deffn
@anchor{Function sb-introspect who-specializes-directly}
@ffindex @sortas{who-specializes-directly sb-introspect} who-specializes-directly [sb-introspect]
@deffn{Function} sb-introspect:who-specializes-directly class-designator
Find the source locations of methods directly specializing on
@code{class-designator}, and return them as an alist of generic function
name, @code{definition-source} pairs.

A method matches the criterion either if it specializes on the same
class as @code{class-designator} designates, or if it eql-specializes on an
instance of the designated class.

Experimental.
@end deffn
@anchor{Function sb-introspect who-specializes-generally}
@ffindex @sortas{who-specializes-generally sb-introspect} who-specializes-generally [sb-introspect]
@deffn{Function} sb-introspect:who-specializes-generally class-designator
Find the source locations of methods specializing on
@code{class-designator} or a subclass of it, and return them as an alist of
generic function name, @code{definition-source} pairs.
@code{definition-source-description} identifies the method.

A method matches the criterion either if it specializes on the
designated class itself or a subclass of it (this includes CLASS-EQ
specializers), or if it eql-specializes on an instance of the
designated class or a subclass of it.

Experimental.
@end deffn
@node sb introspect allocation
@subsection Allocation

@anchor{Function sb-introspect allocation-information}
@ffindex @sortas{allocation-information sb-introspect} allocation-information [sb-introspect]
@deffn{Function} sb-introspect:allocation-information object
Returns information about the allocation of @code{object}. The primary return
value indicates the general type of allocation: @code{:immediate}, @code{:heap},
@code{:stack}, or @code{:foreign}.

Non-NIL secondary return values provide additional information about
the allocation.

For @code{:heap} objects the secondary value is a plist:

  @code{:space}
    Indicates the heap segment the object is allocated in.

  @code{:generation}
    The current generation of the object: 0 for nursery, 6 for pseudo-static
    generation loaded from core. (GENCGC and @code{:space} @code{:dynamic} only.)

  @code{:large}
    Indicates a "large" object subject to non-copying
    promotion. (GENCGC and @code{:space} @code{:dynamic} only.)

  @code{:boxed}
    Indicates that the object is allocated in a boxed region. Unboxed
    allocation is used for e.g. specialized arrays after they have survived one
    collection. (GENCGC and @code{:space} @code{:dynamic} only.)

  @code{:pinned}
    Indicates that the page(s) on which the object resides are kept live due
    to conservative references. Note that object may reside on a pinned page
    even if @code{:pinned} is @code{nil} if the GC has not had the need to mark the page
    as pinned. (GENCGC and @code{:space} @code{:dynamic} only.)

  @code{:write-protected}
    Indicates that the page on which the object starts is write-protected,
    which indicates for @code{:boxed} objects that it hasn't been written to since
    the last GC of its generation. (GENCGC and @code{:space} @code{:dynamic} only.)

  @code{:page}
    The index of the page the object resides on. (GENCGC and @code{:space} @code{:dynamic}
    only.)

For @code{:stack} objects, the secondary value is the thread on whose stack
the object is allocated.

Expected use-cases include introspection to gain insight into allocation and
GC behaviour and restricting memoization to heap-allocated arguments.

Experimental: interface subject to change.
@end deffn
@anchor{Function sb-introspect map-root}
@ffindex @sortas{map-root sb-introspect} map-root [sb-introspect]
@deffn{Function} sb-introspect:map-root function object &key simple ext
Call @code{function} with all non-immediate objects pointed to by @code{object}.
Returns @code{object}.

If @code{simple} is true (default is @code{nil}), elides those pointers that are not
notionally part of certain built-in objects but backpointers to a
conceptual parent: e.g. elides the pointer from a @code{symbol} to the
corresponding @code{package}.

If @code{ext} is true (default is @code{t}), includes some pointers that are not
actually contained in the object but found in certain well-known
indirect containers: @code{fdefinition}s, @code{eql} specializers, classes, and
thread-local symbol values in other threads fall into this category.

@quotation
@emph{Note}: calling @code{map-root} with a THREAD does not currently map over
conservative roots from the thread registers and interrupt contexts.
@end quotation

Experimental: interface subject to change.
@end deffn