MethodAnalysis.jl

visit(operation, obj; print::Bool=false)

Scan obj and all of its "sub-objects" (e.g., functions if obj::Module, methods if obj::Function, etc.) recursively. operation(x) should return true if visit should descend into "sub-objects" of x.

If print is true, each visited object is printed to standard output.

Example

To collect all MethodInstances of a function,

julia> mis = Core.MethodInstance[];

julia> visit(findfirst) do x
           if isa(x, Core.MethodInstance)
               push!(mis, x)
               return false
           end
           true
       end

julia> length(mis)
34

The exact number of MethodInstances will depend on what code you've run in your Julia session.

visit(operation; print::Bool=false)

Scan all loaded modules with operation. See visit(operation, obj) for further detail.

Example

Collect all loaded modules, even if they are internal.

julia> mods = Module[];

julia> visit() do x
           if isa(x, Module)
               push!(mods, x)
               return true
           end
           false
       end

julia> mods 113-element Array{Module,1}: Random Random.DSFMT [...]

visit_backedges(operation, obj)

Visit the backedges of obj and apply operation to each. operation may need to be able to handle two call forms, operation(mi) and operation(sig=>mi), where mi is a MethodInstance and sig is a Tuple-type. The latter arises from either invoke calls or MethodTable backedges.

operation(edge) should return true if the backedges of edge should in turn be visited, false otherwise. However, no MethodInstance will be visited more than once.

The set of visited objects includes obj itself. For example, visit_backedges(operation, f::Function) will visit all methods of f, and this in turn will visit all MethodInstances of these methods.

visit_withmodule(operation; print::Bool=false)
visit_withmodule(operation, obj, mod; print::Bool=false)

Similar to visit, except that operation should have signature operation(x, mod) where mod is either:

• the module in which x was found, or
• nothing if x is itself a top-level module.

If you're visiting underneath a specific object obj, you must supply mod, the module (or nothing) in which obj would be found.

all_backedges(mi::MethodInstance)

Return a list of all backedges (direct and indirect) of mi.

direct_backedges(f::Function; skip=true)

Collect all backedges for a function f as pairs instance=>caller or sig=>caller pairs. The latter occur for MethodTable backedges. If skip is true, any caller listed in a MethodTable backedge is omitted from the instance backedges.

direct_backedges(mi::MethodInstance)

A vector of all direct backedges of mi. This is equivalent to mi.backedges except that it's "safe," meaning it returns an empty list even when mi.backedges is not defined.

terminal_backedges(mi::MethodInstance)

Obtain the "ultimate callers" of mi, i.e., the reason(s) mi was compiled.

with_all_backedges(itr)

Return all MethodInstances detected when iterating through items in itr and any their backedges. The result includes both MethodTable and MethodInstance backedges.

mi = methodinstance(f, types)
mi = methodinstance(tt::Type{<:Tuple})

Return the MethodInstance mi for function f and the given types, or for the complete signature tt. If no version compiled for these types exists, returns nothing.

Examples

julia> f(x, y::String) = 2x; f(x, y::Number) = x + y;

julia> f(1, "hi"); f(1, 1.0);

julia> methodinstance(f, (Int, String))
MethodInstance for f(::Int64, ::String)

julia> methodinstance(Tuple{typeof(f), Int, String})
MethodInstance for f(::Int64, ::String)

methodinstances()
methodinstances(top)

Collect all MethodInstances, optionally restricting them to a particular module, function, method, or methodlist.

Examples

julia> sin(π/2)
1.0

julia> sin(0.8f0)
0.7173561f0

julia> methodinstances(sin)
2-element Vector{Core.MethodInstance}:
 MethodInstance for sin(::Float64)
 MethodInstance for sin(::Float32)

julia> m = which(convert, (Type{Bool}, Real))
convert(::Type{T}, x::Number) where T<:Number in Base at number.jl:7

julia> methodinstances(m)
68-element Vector{Core.MethodInstance}:
 MethodInstance for convert(::Type{UInt128}, ::Int64)
 MethodInstance for convert(::Type{Int128}, ::Int64)
 MethodInstance for convert(::Type{Int64}, ::Int32)
 MethodInstance for convert(::Type{UInt64}, ::Int64)
 ⋮

Note the method m was broader than the signature we queried with, and the returned MethodInstances reflect that breadth. See methodinstances for a more restrictive subset, and methodinstances_owned_by for collecting MethodInstances owned by specific modules.

methodinstances(f, types)
methodinstances(tt::Type{<:Tuple})

Return all MethodInstances whose signature is a subtype of types.

Example

julia> methodinstances(convert, (Type{Bool}, Real))
2-element Vector{Core.MethodInstance}:
 MethodInstance for convert(::Type{Bool}, ::Bool)
 MethodInstance for convert(::Type{Bool}, ::Int64)

Compare this to the result from methodinstance.

mis = methodinstances_owned_by(mod::Module; include_child_modules::Bool=true, kwargs...)

Return a list of MethodInstances that are owned by mod. If include_child_modules is true, this includes sub-modules of mod, in which case kwargs are passed to child_modules.

The primary difference between methodinstances(mod) and methodinstances_owned_by(mod) is that the latter excludes MethodInstances that belong to re-exported dependent packages.

mods = child_modules(mod::Module; external::Bool=false)

Return a list that includes mod and all sub-modules of mod. By default, modules loaded from other sources (e.g., packages or those defined by Julia itself) are excluded, even if exported (or @reexported, see https://github.com/simonster/Reexport.jl), unless you set external=true.

Examples

julia> module Outer
       module Inner
       export Base
       end
       end
Main.Outer

julia> child_modules(Outer)
2-element Vector{Module}:
 Main.Outer
 Main.Outer.Inner

julia> child_modules(Outer.Inner)
1-element Vector{Module}:
 Main.Outer.Inner

Extended help

In the example above, because of the export Base, the following visit-based implementation would also collect Base and all of its sub-modules:

julia> mods = Module[]
Module[]

julia> visit(Outer) do item
           if item isa Module
               push!(mods, item)
               return true
           end
           return false
       end

julia> Base ∈ mods
true

julia> length(mods) > 20
true

call_type(tt)

Split a signature type like Tuple{typeof(f),ArgTypes...} back out to (f, Tuple{ArgTypes...})

callers = findcallers(f, argmatch::Union{Nothing,Function}, mis; callhead=:call | :iterate)

Find "static" callers of a function f with inferred argument types for which argmatch(types) returns true. Optionally pass nothing for argmatch to allow any calls to f. mis is the list of MethodInstances you want to check, for example obtained from methodinstances.

callhead controls whether you're looking for an ordinary (:call) or a splatted (varargs) call (:iterate).

callers is a vector of CallMatch objects.

Examples

f(x) = rand()
function g()
    a = f(1.0)
    z = Any[7]
    b = f(z[1]::Integer)
    c = f(z...)
    return nothing
end

g()
mis = union(methodinstances(f), methodinstances(g))

# callhead = :call is the default
callers1 = findcallers(f, argtyps->length(argtyps) == 1 && argtyps[1] === Float64, mis)

# Get the partial-inference case with known number of arguments (this is definitely :call)
callers2 = findcallers(f, argtyps->length(argtyps) == 1 && argtyps[1] === Integer, mis; callhead=:call)

# Get the splat call
callers3 = findcallers(f, argtyps->length(argtyps) == 1 && argtyps[1] === Vector{Any}, mis; callhead=:iterate)

hasbox(mi::MethodInstance)

Return true if the code for mi has a Core.Box. This often arises from a limitation in Julia's type-inference, see https://docs.julialang.org/en/v1/manual/performance-tips/#man-performance-captured.

minmaxs = worlds(mi::MethodInstance)

Collect the (min,max) world-age pairs for all CodeInstances associated with mi.

CallMatch

A structure to summarize a "matching" caller/callee pair. The fields are:

• mi: the MethodInstance for the caller
• src: its corresponding CodeInfo
• sparams: the type parameters for the caller, given mi's signature (alternatively use mi.sparam_vals)
• line: the statement number (in SSAValue sense) on which the call occurs
• argtypes: the caller's inferred types passed as arguments to the callee