Crate hotpatch

Changing function definitions at runtime.

This crate is primarily used to load new function definitions from shared object files in an exceedingly easy way.

Short Example

The following shows how dead-simple this crate is to use:

// main.rs
use hotpatch::patchable;

#[patchable]
fn foo() { }

fn main() -> Result<(), Box<dyn std::error::Error>> {
  foo(); // does nothing
  foo.hotpatch_lib("libsomething.so")?;
  foo(); // does something totally different!
  Ok(())
}

What about defining a patch? Also easy:

// lib.rs
use hotpatch::patch;
 
#[patch]
fn foo() { }

For more examples see the git repo.

Features

For reference, this crate recognizes the following features:

• allow-main: Allow setting main as #[patchable]. Only useful if using #[start] or #[main].
• redirect-main: Same as allow-main but also generates a stub #[main] to call the Patchable. If you just want to hotpatch main, this is probably the right feature. Requires nightly and #[feature(main)].
• large-signatures: Tweaks the variadic generics engine. See hotpatch_fn.

Warnings

Under normal operation, this crate provides type saftey, thread saftey, namepace saftey, and a whole bunch of other guarentees. However, use of this crate is still playing with fire.

The one thing that cannot be checked against is call stack saftey. Because Patchable uses RwLocks the current thread is blocked when trying to hotpatch a function. This ensures that an out-of-date function body cannot be ran. However if the function being hotpatched is the current function or anywhere within the call stack (eg patching a function that called the current function) a deadlock will occur. Be careful!

The try methods within Patchable provide additional checks for this, but may cause other problems in multithreaded environments.

Bypassing Thread Saftey

The previous section mentions being unable to hotpatch currently running functions. This is a deliberate saftey feature. However, it can be bypassed by using the force methods within Patchable. This allows multiple functions definitions to run at once. This is unsafe, but allows for some really interesting things such as hotpatching main.

Structs

HotpatchExport	Created by #[patch]. Internal use only.
Patchable	Created by #[patchable]. A functor capable of overwriting its own function.

Attribute Macros

patch	Transforms a function into a HotpatchExport capable of being exported and changing the behavior of a function in a seperate binary at runtime. The original function is preserved.
patchable	Transforms a function into a Patchable capable of having its behavior redefined at runtime.