Base: add record_calls / invalidate_calls for compilation benchmarking

Add `Base.record_calls`, `Base.@record_calls`, and `Base.invalidate_calls`
for scoped invalidation of a call's cached native code and inferred IR.
These are intended for statistical benchmarking of compilation time
(e.g. `@benchmark foo($x) compilation=true` in BenchmarkTools): each
sample can invalidate just the target `MethodInstance` and force a fresh
codegen on the next dispatch, without bumping the global world counter
or propagating to backedges.

The C helper `invalidate_method_instance_caches` is renamed to
`jl_method_instance_invalidate_caches` and exported via julia.h so the
Julia-side wrapper can `ccall` it directly.

Co-Authored-By: Claude <[email protected]>

Author: IanButterworth

base/reflection.jl

@@ -87,6 +87,63 @@ function method_instance(@nospecialize(f), @nospecialize(t);
     return method_instance(tt; world, method_table)
 end
 
+"""
+    Base.record_calls(f, types::Type{<:Tuple}) -> Vector{Core.MethodInstance}
+
+Return the `MethodInstance`s that must be invalidated in order to force
+recompilation of the call `f(args...)` where `types === Tuple{map(typeof, args)...}`.
+
+Only the entry-point `MethodInstance` is returned: the next dispatch to it
+will re-infer and re-codegen along with any callees that are inlined into
+it. Callees that are not inlined remain cached, so invalidating the returned
+instances measures the cost of compiling `f` itself (with its inlining
+decisions) rather than of rebuilding the entire transitive call tree.
+
+See also [`Base.invalidate_calls`](@ref), [`Base.@record_calls`](@ref).
+"""
+function record_calls(@nospecialize(f), @nospecialize(types::Type{<:Tuple}))
+    mi = method_instance(f, types)
+    mi === nothing && error("could not resolve MethodInstance for ", f, " with argument types ", types)
+    return Core.MethodInstance[mi]
+end
+
+"""
+    Base.@record_calls f(args...)
+
+Convenience macro equivalent to `Base.record_calls(f, Tuple{map(Core.Typeof, args)...})`.
+"""
+macro record_calls(ex)
+    Meta.isexpr(ex, :call) || error("@record_calls expects a call expression, got $(ex)")
+    f = ex.args[1]
+    args = ex.args[2:end]
+    types = Expr(:curly, :Tuple, (:(Core.Typeof($(esc(a)))) for a in args)...)
+    return :(record_calls($(esc(f)), $types))
+end
+
+"""
+    Base.invalidate_calls(mis)
+
+Invalidate the cached native code and inferred IR for each `MethodInstance`
+in `mis`, forcing a recompile the next time each is dispatched. This is a
+pure cache flush: it does not bump the global world counter and does not
+propagate to backedges, so other code compiled against `mis` is unaffected.
+
+Intended for statistical benchmarking of compilation time. See also
+[`Base.record_calls`](@ref).
+"""
+function invalidate_calls(mis)
+    world = get_world_counter()
+    # Cap cache validity *below* the current world so dispatch at this world
+    # re-enters codegen. We do NOT bump the global world counter (that would
+    # force everything else to reinfer too).
+    cap = world == 0 ? UInt(0) : world - UInt(1)
+    for mi in mis
+        mi isa Core.MethodInstance || throw(ArgumentError(string("expected Core.MethodInstance, got ", typeof(mi))))
+        ccall(:jl_method_instance_invalidate_caches, Cvoid, (Any, Csize_t), mi, cap)
+    end
+    return nothing
+end
+
 default_debug_info_kind() = unsafe_load(cglobal(:jl_default_debug_info_kind, Cint))
 
 # this type mirrors jl_cgparams_t (documented in julia.h)

src/gf.c

@@ -5268,8 +5268,11 @@ JL_DLLEXPORT void jl_extern_c(jl_value_t *name, jl_value_t *declrt, jl_tupletype
     JL_GC_POP();
 }
 
-// Drop all method caches and increment world age as if adding a method that intersects everything
-static void invalidate_method_instance_caches(jl_method_instance_t *mi, size_t world)
+// Drop cached native code and inferred IR for a single MethodInstance by
+// setting `max_world` on each live CodeInstance in its cache chain. This does
+// NOT bump the global world counter and does NOT propagate to backedges,
+// making it a pure cache flush suitable for compilation benchmarking.
+JL_DLLEXPORT void jl_method_instance_invalidate_caches(jl_method_instance_t *mi, size_t world)
 {
     if ((jl_value_t*)mi == jl_nothing)
         return;
@@ -5295,12 +5298,12 @@ static int invalidate_all_specializations(jl_typemap_entry_t *def, void *closure
         size_t i, l = jl_svec_len(specializations);
         for (i = 0; i < l; i++) {
             jl_method_instance_t *mi = (jl_method_instance_t*)jl_svecref(specializations, i);
-            invalidate_method_instance_caches(mi, world);
+            jl_method_instance_invalidate_caches(mi, world);
         }
     }
     else if (specializations != NULL) {
         jl_method_instance_t *mi = (jl_method_instance_t*)specializations;
-        invalidate_method_instance_caches(mi, world);
+        jl_method_instance_invalidate_caches(mi, world);
     }
     JL_UNLOCK(&method->writelock);
     return 1;

src/julia.h

@@ -1932,6 +1932,7 @@ JL_DLLEXPORT jl_code_info_t *jl_copy_code_info(jl_code_info_t *src);
 JL_DLLEXPORT size_t jl_get_world_counter(void) JL_NOTSAFEPOINT;
 JL_DLLEXPORT size_t jl_get_tls_world_age(void) JL_NOTSAFEPOINT;
 JL_DLLEXPORT void jl_drop_all_caches(void);
+JL_DLLEXPORT void jl_method_instance_invalidate_caches(jl_method_instance_t *mi, size_t world);
 JL_DLLEXPORT jl_value_t *jl_box_bool(int8_t x) JL_NOTSAFEPOINT;
 JL_DLLEXPORT jl_value_t *jl_box_int8(int8_t x) JL_NOTSAFEPOINT;
 JL_DLLEXPORT jl_value_t *jl_box_uint8(uint8_t x) JL_NOTSAFEPOINT;

test/worlds.jl

@@ -627,3 +627,30 @@ let
     @test rettype_side_effect == "blah"
     ccall(:strlen, rettype_with_side_effect(), (Cstring,), "xx")
 end
+
+# Base.Experimental.record_calls / invalidate_calls: scoped cache invalidation
+# used by BenchmarkTools-style compilation benchmarks. Must drop cached native
+# code without bumping world age or touching backedges.
+module CompileRecordTest
+using Test
+recorded_target(x) = x * x + 1
+recorded_target(1.0)  # force compile
+let mis = Base.@record_calls recorded_target(1.0)
+    @test length(mis) == 1
+    mi = mis[1]
+    @test mi isa Core.MethodInstance
+    ci = @atomic mi.cache
+    @test ci !== nothing
+    @test (@atomic ci.max_world) == typemax(UInt)
+    world_before = Base.get_world_counter()
+    Base.invalidate_calls(mis)
+    # World counter must not move (this is the key distinction from ordinary invalidation)
+    @test Base.get_world_counter() == world_before
+    # Cached CodeInstance is now capped
+    @test (@atomic ci.max_world) < typemax(UInt)
+    # Next call re-specializes; a fresh CodeInstance appears on the cache chain
+    recorded_target(1.0)
+    ci2 = @atomic mi.cache
+    @test ci2 !== ci || (@atomic ci2.max_world) == typemax(UInt)
+end
+end