hook_macro

Procedural macro for generating runtime hook systems with before/on/after callbacks.

Features

🔧 Automatically generates before, on, and after hook chains
🌐 Supports FFI export for C/C++ interop
🛡️ Reentrancy protection to prevent infinite loops
🎨 Customizable naming with prefix, suffix, and mangling options
💾 Configurable fallback return value when hooks interrupt execution

Installation

Add to your Cargo.toml:

[dependencies]
hook_macro = "0.1"

Quick Start

use hook_macro::register_hook;

#[register_hook]
fn add_one(x: i32) -> i32 {
    x + 1
}

fn main() {
    // Register hooks
    register_before_add_one(|x| {
        println!("Before: {}", x);
        false // Return true to interrupt execution
    });

    register_on_add_one(|x| {
        println!("On: {}", x);
        false
    });

    register_after_add_one(|x| {
        println!("After: {}", x);
        false
    });

    // Call the wrapped function
    let result = unsafe { add_one(5) };
    println!("Result: {}", result);
}

Examples

With Fallback

use hook_macro::register_hook;

#[register_hook(fallback = "0")]
fn divide(a: i32, b: i32) -> i32 {
    a / b
}

fn main() {
    // Interrupt the call and return fallback value
    register_before_divide(|_| true); // Always interrupt

    let result = unsafe { divide(10, 2) };
    assert_eq!(result, 0); // Returns fallback value
}

Custom Naming

use hook_macro::register_hook;

// Rename the original implementation
#[register_hook(suffix = "_original")]
fn my_function(x: i32) -> i32 {
    x * 2
}

// Or use custom prefix
#[register_hook(prefix = "impl_")]
fn another_function(x: i32) -> i32 {
    x + 1
}

// Or fully control the name
#[register_hook(mangling = "custom_impl_name")]
fn third_function(x: i32) -> i32 {
    x - 1
}

Generated API

For a function foo with one parameter, the macro generates:

Function	Description
`register_before_foo(hook)`	Register a before hook
`register_on_foo(hook)`	Register an on hook
`register_after_foo(hook)`	Register an after hook
`clear_foo_hooks()`	Clear all hooks

Hook Types

With parameter T:

type BeforeFooHook = unsafe extern "C" fn(*mut T) -> bool;
type OnFooHook = unsafe extern "C" fn(*const T) -> bool;
type AfterFooHook = unsafe extern "C" fn(*const T) -> bool;

Without parameters:

type BeforeFooHook = unsafe extern "C" fn() -> bool;
type OnFooHook = unsafe extern "C" fn() -> bool;
type AfterFooHook = unsafe extern "C" fn() -> bool;

Return true from a hook to interrupt the chain and stop execution.

Attribute Parameters

Parameter	Type	Default	Description
`fallback`	string	`Default::default()`	Return value when hooks interrupt execution
`prefix`	string	`""`	Prefix for the original implementation name
`suffix`	string	`"_impl"`	Suffix for the original implementation name
`mangling`	string	None	Full custom name for the original implementation

Limitations

Functions can have at most one parameter
Parameter type must implement Clone
Return type must implement Default (unless fallback is specified)

License

This project is licensed under the LICENSE.

hook_macro 0.1.0