Struct Hook 

pub struct Hook<F: 'static> { /* private fields */ }

A hook on a function, returned disabled by a generated function’s hook.

F is the function’s generated Signature type. While the guard is alive, this mod can’t hook the function again.

Dropping

Dropping the guard disables the hook as disable does, and the function can then be hooked again. If disabling fails, the hook stays in place and the function stays reserved. A thread still running the closure is unaffected, as nothing it uses is freed.

Threads and batches

enable and disable suspend every other thread of the process while patching, so don’t call them from inside the hooked function. Inside an imping_hook::batch they are queued and applied together when the batch ends. The _unsuspended variants skip the suspension and take effect at once, even inside a batch.

Implementations

impl<F: Copy + 'static> Hook<F>

pub fn enable(&self) -> Result<()>

Redirects the function to the hook’s closure.

Suspends other threads while patching; see Hook for threads and batches.

Errors

Error::Hook if patching fails.

pub fn disable(&self) -> Result<()>

Restores the function, so calls skip the closure.

Suspends other threads while patching; see Hook for threads and batches.

Errors

Error::Hook if patching fails.

pub unsafe fn enable_unsuspended(&self) -> Result<()>

Redirects the function to the hook’s closure without suspending other threads.

Faster than enable; see Hook for threads and batches.

Errors

Error::Hook if patching fails.

Safety

No other thread may execute the function’s first instructions while they are patched, or it may run a half-written instruction.

pub unsafe fn disable_unsuspended(&self) -> Result<()>

Restores the function without suspending other threads.

Faster than disable; see Hook for threads and batches.

Errors

Error::Hook if patching fails.

Safety

No other thread may execute the function’s first instructions while the original ones are written back.

pub fn is_enabled(&self) -> bool

Returns whether the function is redirected to the closure.

pub fn original(&self) -> F

Returns the original, unhooked function.

It stays valid for the rest of the process, even after the guard is dropped.

pub fn leak(self)

Keeps the hook, in its current state, for the rest of the process.

The function stays reserved, and the mod must never be unloaded.

Trait Implementations

impl<F: 'static> Debug for Hook<F>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<F: 'static> Drop for Hook<F>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.