[−][src]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 settingmain
as#[patchable]
. Only useful if using#[start]
or#[main]
.redirect-main
: Same asallow-main
but also generates a stub#[main]
to call thePatchable
. If you just want to hotpatchmain
, this is probably the right feature. Requires nightly and#[feature(main)]
.large-signatures
: Tweaks the variadic generics engine. Seehotpatch_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 RwLock
s
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 |
Patchable | Created by |
Attribute Macros
patch | Transforms a function into a |
patchable | Transforms a function into a |