Introspection and Thread Safety

MonoMod.RuntimeDetour can tell you which detours are applied to a method, notify you when that changes, and let you hold a method's lock while you inspect it. This page documents DetourManager, the *Info introspection types, and how the detour chain behaves under concurrency and when hooks modify the chain from inside a hooked call.

DetourManager

MonoMod.RuntimeDetour.DetourManager is a static class:

Member Description
MethodDetourInfo GetDetourInfo(MethodBase method) The introspection object for a managed method's chain.
FunctionDetourInfo GetNativeDetourInfo(IntPtr function) The introspection object for a native function's chain.
event Action<DetourInfo>? DetourApplied / DetourUndone Raised for any managed Hook applied or undone, on any method.
event Action<ILHookInfo>? ILHookApplied / ILHookUndone Raised for any ILHook applied or undone.
event Action<NativeDetourInfo>? NativeDetourApplied / NativeDetourUndone Raised for any NativeHook applied or undone.

The global events are useful for mod loaders that want to log or display which mod hooks what.

MethodDetourInfo

Member Description
Method The method this object represents.
IsDetoured true if at least one Hook or ILHook is applied.
HasActiveCall true while some thread is executing the detour chain. Only ever true when detours are applied.
Detours A DetourCollection (enumerable of DetourInfo) in chain order.
ILHooks An ILHookCollection (enumerable of ILHookInfo).
FirstDetour The first DetourInfo in the chain, or null.
DetourApplied, DetourUndone, ILHookApplied, ILHookUndone Per-method events.
EnterLock(ref bool lockTaken) / ExitLock() Take and release the method's detour lock.
WithLock() Returns a Lock ref struct; dispose it (with using) to release.

While you hold the lock, other threads cannot modify that method's chain, so enumeration is consistent:

var info = DetourManager.GetDetourInfo(typeof(Player).GetMethod("TakeDamage")!);
using (info.WithLock())
{
    foreach (DetourInfo d in info.Detours)
        Console.WriteLine($"{d.Config?.Id ?? "(no config)"} -> {d.Entry}  applied={d.IsApplied}");

    foreach (ILHookInfo i in info.ILHooks)
        Console.WriteLine($"IL: {i.Config?.Id ?? "(no config)"} {i.ManipulatorMethod}");
}

This pattern comes from DetourOrderTest.

DetourInfo and ILHookInfo

DetourInfo (for Hooks) and ILHookInfo (for ILHooks) both derive from DetourBase. They represent a detour without keeping it alive, so holding one does not prevent the underlying Hook from being collected and undone.

Member On Description
Method both The owning MethodDetourInfo.
IsApplied both Whether the detour is applied.
Config both Its DetourConfig?.
Apply() / Undo() both Apply or undo the underlying detour.
Entry DetourInfo The hook's target method (same as Hook.Target).
Next DetourInfo The next detour in the chain, or null.
ManipulatorMethod ILHookInfo The MethodInfo of the manipulator delegate.

Get these from a live detour with Hook.DetourInfo and ILHook.HookInfo.

Native Detours

The native side mirrors the managed one: FunctionDetourInfo (Function, IsDetoured, HasActiveCall, Detours, FirstDetour, DetourApplied, DetourUndone, EnterLock/ExitLock/WithLock) and NativeDetourInfo (Function, IsApplied, Config, Apply(), Undo(), Entry = the hook delegate's method, Next). Get a NativeDetourInfo from NativeHook.DetourInfo.

Thread Safety

Modifying a chain is synchronized with calls through it:

  • Only one thread modifies a given chain at a time.
  • A modification waits until all other threads have left the hooked method before changing anything.
  • While a modification is in progress, new calls to the hooked method from other threads block until it finishes.
  • This blocking applies only to the outermost call on each thread's stack. Nested (recursive) calls do not block, to avoid deadlocks.

The orig delegate is safe to call while the chain is on your stack. Calling a stored orig later is not thread-safe and may not call the chain as it currently exists.

Hot-Patching the Chain While It Runs

Hooks may add or remove hooks, including themselves, from inside a hooked call (directly, or from code they call). According to docs/RuntimeDetour/implementation/ChainHotPatching.md:

  • The chain is modified immediately.
  • A newly added hook that sorts before the currently running hook is not called until the next invocation of the method.
  • A newly added hook that sorts after the current one becomes part of the chain right away and is called when control passes to the next hook.
  • When a hook is removed while the method is on the stack, its orig trampoline is "stolen" by the detour manager instead of being returned to the pool, and kept alive until the method has fully left the stack. Using it after that is undefined behavior.

See Also