ZJIT: Deferral mechanism for cold-path re-profiling

Add escalating deferral for recompilations where the HIR still has
unresolved NoProfile sends (>25% ratio) or non-monomorphic ivars.
When triggered, the ISEQ returns to the interpreter for 1K calls to
collect fresh profile data before V2 compilation.

- deferred_threshold() with escalating levels (call_threshold/1K/100K)
- Pre-HIR gate in gen_iseq_entry_point and function_stub_hit
- Post-HIR quality check triggers deferral on recompilations
- count_no_profile_sends/has_not_monomorphic_ivars on Function
- defer_count/deferred_stub_hits fields on IseqPayload
- trigger_recompilation resets deferral state

Author: nmeans

zjit/src/codegen.rs

@@ -24,7 +24,7 @@ use crate::backend::lir::{self, Assembler, C_ARG_OPNDS, C_RET_OPND, CFP, EC, NAT
 use crate::hir::{iseq_to_hir, BlockId, Invariant, RangeType, SideExitReason::{self, *}, SpecialBackrefSymbol, SpecialObjectType};
 use crate::hir::{Const, FrameState, Function, Insn, InsnId, SendFallbackReason};
 use crate::hir_type::{types, Type};
-use crate::options::get_option;
+use crate::options::{get_option, rb_zjit_call_threshold};
 use crate::cast::IntoUsize;
 
 /// At the moment, we support recompiling each ISEQ only once.
@@ -52,6 +52,16 @@ pub extern "C" fn rb_zjit_count_side_exit(payload_raw: *mut std::ffi::c_void) {
 static GLOBAL_RECOMPILE_COUNT: AtomicU64 = AtomicU64::new(0);
 const MAX_GLOBAL_RECOMPILATIONS: u64 = 50;
 
+/// Escalating threshold for deferred re-profiling. Higher deferral levels
+/// give cold branches progressively more time to warm up.
+fn deferred_threshold(defer_count: u32) -> u32 {
+    match defer_count {
+        1 => unsafe { rb_zjit_call_threshold as u32 },
+        2 => 1_000,
+        _ => 100_000,
+    }
+}
+
 fn trigger_recompilation(payload_raw: *mut std::ffi::c_void, iseq: IseqPtr) {
     if MAX_GLOBAL_RECOMPILATIONS > 0 {
         let prev = GLOBAL_RECOMPILE_COUNT.fetch_add(1, Ordering::Relaxed);
@@ -64,6 +74,12 @@ fn trigger_recompilation(payload_raw: *mut std::ffi::c_void, iseq: IseqPtr) {
     debug!("trigger_recompilation: recompiling {}", iseq_get_location(iseq, 0));
     incr_counter!(recompile_count);
     payload.profile.reset_for_recompile();
+
+    // Reset deferral state so V2 compilation goes straight to building the HIR.
+    // If the HIR still has unresolved issues, the post-HIR deferral trigger handles escalation.
+    payload.defer_count = 0;
+    payload.deferred_stub_hits = 0;
+
     if let Some(version) = payload.versions.last_mut() {
         let version = unsafe { version.as_mut() };
         version.status = IseqStatus::Invalidated;
@@ -232,11 +248,56 @@ fn gen_iseq_entry_point(cb: &mut CodeBlock, iseq: IseqPtr, jit_exception: bool)
         return Err(CompileError::ExceptionHandler);
     }
 
+    // If this ISEQ is in a deferred re-profiling window, don't compile yet.
+    // Count this interpreter entry toward the threshold and keep the ISEQ
+    // running in the interpreter with profiling active. Both interpreter
+    // entries and stub fallbacks count toward the same escalating threshold.
+    {
+        let payload = get_or_create_iseq_payload(iseq);
+        if payload.defer_count > 0 {
+            let threshold = deferred_threshold(payload.defer_count);
+            if payload.deferred_stub_hits < threshold {
+                let call_threshold = unsafe { rb_zjit_call_threshold as u32 };
+                payload.deferred_stub_hits += call_threshold;
+                unsafe { rb_iseq_reset_jit_func(iseq) };
+                return Err(CompileError::DeferredForReprofiling);
+            }
+        }
+    }
+
     // Compile ISEQ into High-level IR
     let function = crate::stats::with_time_stat(Counter::compile_hir_time_ns, || compile_iseq(iseq).inspect_err(|_| {
         incr_counter!(failed_iseq_count);
     }))?;
 
+    // Adaptive deferral for recompilations. First compilations never defer.
+    // For recompilations (latest version invalidated), if the HIR has a
+    // significant fraction of unresolved sends or any unresolved ivars,
+    // defer for 1K interpreter calls to exercise cold branches.
+    // A single dead-branch NoProfile send does NOT trigger deferral —
+    // ISEQs where most sends are well-profiled compile immediately.
+    if get_option!(recompile_threshold) > 0 {
+        let payload = get_or_create_iseq_payload(iseq);
+        let is_recompile = payload
+            .versions
+            .last()
+            .map(|v| unsafe { v.as_ref() }.status == IseqStatus::Invalidated)
+            .unwrap_or(false);
+        // Use ratio-based check for sends: only defer if >25% of sends lack profiles.
+        let (no_profile_sends, total_sends) = function.count_no_profile_sends();
+        let sends_need_deferral = total_sends > 0 && no_profile_sends * 4 > total_sends;
+        let has_unresolved = sends_need_deferral || function.has_not_monomorphic_ivars();
+        if is_recompile && payload.defer_count < 2 && has_unresolved {
+            payload.defer_count = 2; // level 2: deferred_threshold(2) = 1K calls
+            payload.deferred_stub_hits = 0;
+            payload.profile.reset_for_recompile();
+            unsafe { rb_zjit_profile_enable(iseq) };
+            unsafe { rb_iseq_reset_jit_func(iseq) };
+            incr_counter!(recompile_count);
+            return Err(CompileError::DeferredForReprofiling);
+        }
+    }
+
     // Compile the High-level IR
     let IseqCodePtrs { start_ptr, .. } = gen_iseq(cb, iseq, Some(&function)).inspect_err(|err| {
         debug!("{err:?}: gen_iseq failed: {}", iseq_get_location(iseq, 0));
@@ -2881,6 +2942,35 @@ c_callable! {
             // code path can be made read-only. But you still need the check as is while holding the VM lock in any case.
             let cb = ZJITState::get_code_block();
             let payload = get_or_create_iseq_payload(iseq);
+
+            // If this ISEQ is being re-profiled after deferral, fall back to
+            // the interpreter — the zjit_* profiling instructions are active
+            // and collect type data on each fallback. The threshold escalates
+            // with each deferral level to give cold branches progressively more
+            // time to warm up. This gate fires for both first-compilation deferrals
+            // (versions empty) and inline-triggered recompilation deferrals
+            // (latest version invalidated).
+            let latest_invalidated = payload.versions.last()
+                .map(|v| unsafe { v.as_ref() }.status == IseqStatus::Invalidated)
+                .unwrap_or(false);
+            if payload.defer_count > 0 && (payload.versions.is_empty() || latest_invalidated) {
+                // Count stub hits toward the deferral threshold for BOTH initial
+                // deferrals (versions empty) and recompilation deferrals (latest
+                // invalidated). Previously, recompilation deferrals returned the
+                // exit trampoline unconditionally without counting, causing the
+                // method to stay in the interpreter indefinitely — a catastrophic
+                // overhead for hot methods (addressable-merge lost 2.5s).
+                let threshold = deferred_threshold(payload.defer_count);
+                payload.deferred_stub_hits += 1;
+                if payload.deferred_stub_hits <= threshold {
+                    // Still collecting profile data — fall back to interpreter
+                    unsafe { Rc::increment_strong_count(iseq_call_ptr as *const IseqCall); }
+                    prepare_for_exit(iseq, cfp, sp, &CompileError::DeferredForReprofiling);
+                    return ZJITState::get_exit_trampoline().raw_ptr(cb);
+                }
+                // Enough profile data collected — fall through to compile
+            }
+
             let last_status = payload.versions.last().map(|version| &unsafe { version.as_ref() }.status);
             let compile_error = match last_status {
                 Some(IseqStatus::CantCompile(err)) => Some(err),

zjit/src/hir.rs

@@ -5679,6 +5679,55 @@ impl Function {
         }
     }
 
+    /// Count how many Send instructions have empty (NoProfile) type profiles.
+    /// Returns (no_profile_count, total_send_count).
+    pub fn count_no_profile_sends(&self) -> (usize, usize) {
+        let Some(profiles) = self.profiles.as_ref() else {
+            return (0, 0);
+        };
+        let mut no_profile = 0;
+        let mut total = 0;
+        for block in self.rpo() {
+            for &insn_id in &self.blocks[block.0].insns {
+                if let Insn::Send { state, .. } = self.find(insn_id) {
+                    total += 1;
+                    let frame_state = self.frame_state(state);
+                    let insn_idx = frame_state.insn_idx;
+                    // Check if the profile entry at this instruction is empty
+                    if let Some(entries) = profiles.types.get(&insn_idx) {
+                        if entries.is_empty() {
+                            no_profile += 1;
+                        }
+                    }
+                }
+            }
+        }
+        (no_profile, total)
+    }
+
+    /// Check if any Send instructions have empty profiles.
+    /// Convenience wrapper around count_no_profile_sends().
+    pub fn has_no_profile_sends(&self) -> bool {
+        self.count_no_profile_sends().0 > 0
+    }
+
+    /// Check if the optimized HIR has any GetIvar/SetIvar instructions that
+    /// weren't optimized by optimize_getivar (i.e., they use the fallback
+    /// rb_vm_getinstancevariable/rb_vm_setinstancevariable path). These
+    /// survive in the HIR when the profiled self type was not monomorphic
+    /// or had no profile data at all.
+    pub fn has_not_monomorphic_ivars(&self) -> bool {
+        for block in self.rpo() {
+            for &insn_id in &self.blocks[block.0].insns {
+                match self.find(insn_id) {
+                    Insn::GetIvar { .. } | Insn::SetIvar { .. } => return true,
+                    _ => {}
+                }
+            }
+        }
+        false
+    }
+
     /// Dump HIR passed to codegen if specified by options.
     pub fn dump_hir(&self) {
         // Dump HIR after optimization

zjit/src/payload.rs

@@ -13,6 +13,11 @@ pub struct IseqPayload {
     pub versions: Vec<IseqVersionRef>,
     /// Number of side exits observed for this ISEQ
     pub side_exit_count: u64,
+    /// How many times this ISEQ has been deferred for re-profiling.
+    /// 0 = not deferred, 1 = first deferral (call_threshold calls), 2 = second (1K calls), etc.
+    pub defer_count: u32,
+    /// How many stub/entry hits have been counted during the current deferral window.
+    pub deferred_stub_hits: u32,
 }
 
 impl IseqPayload {
@@ -21,6 +26,8 @@ impl IseqPayload {
             profile: IseqProfile::new(iseq_size),
             versions: vec![],
             side_exit_count: 0,
+            defer_count: 0,
+            deferred_stub_hits: 0,
         }
     }
 }