Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
predicator
predicator is a rust crate that lets you write plug ins that are can be loaded and unloaded and optimized at runtime, in Rust and any other language that LLVM JIT supports. It's ideal for filters, security checks and short-lived snippets of code that live for 10s to 100s of seconds in long-lived processes.
It is thread safe, but plugins are limited to #[no_std]
crates at this time. A longer term plan is to add support for hosting cargo, and experimenting with symbol resolvers.
Statically-linked programs will work, but if they use a third-party library (even the libc), then they'll need to be specially compiled to pull in those definitions.
Impatient to get getting?
Look at src/main.rs
. This is all you need to create and load a plug in. Creation can be in a separate process, or even on a separate machine.
Demonstrate it works on your machine with cargo run
. You'll need Rust nightly. Tested on Mac OS X as of 9th June 2017.
Writing a Plug In
Setting up Cargo.toml
The values in Cargo.toml
need to be carefully set in order to generate a suitable plug-in.
Firstly, make sure the [profile]
section contains these two entries exactly:-
[]
= 3
= true
= false
= true
= true
= 1
= 'abort'
[]
= 3
= false
= false
= true
= false
= 1
= 'abort'
The settings of lto = true
is particularly important. The setting of panic = abort
isn't strictly necessary, but, as there is no way to pass panics in a LLVM JIT plugin back to Rust, makes development a little easier, as panics will die safely during development and debug testing.
Secondly, add or replace the [lib]
section so it matches this exactly:-
= ["bin"]
Writing the code for a LLVM JIT plugin
A LLVM JIT plugin needs some boiler plate code in order to work. Put this code at the top of your lib.rs
:-
extern crate libc;
!
extern
pub extern
pub extern
/// Change this code to run unit tests when compiled in `debug` mode
/// Return a non-zero value to mark a test failure
This code does the following:-
- Tells the Rust compiler to use just the
core
crate (also known aslibcore
)- This means anything requiring (heap) memory allocation isn't available
- No collections (eg
Vec
,HashSet
, etc) - No
Box
,Rc
orArc
- No strings (
String
,str
,CString
,CStr
,OsString
andOsStr
) - No paths (
Path
,PathBuf
) - And other similar restrictions
- No collections (eg
- Also, that code that panics is not particularly useful
- This means anything requiring (heap) memory allocation isn't available
- Tells the Rust compiler that we will supply language item functions missing from
core
- Tells the Rust compiler that we will use its toolchain's version of the
libc
crate (not strictly necessary in advanced scenarios) - Tells the Rust compiler not to generate the usual logic to support Rust's
main()
function, as we don't need them for a plugin - Uses the
libc
crate; without it, the plugin won't compile as it relies on the libc start files likecrt1.o
- Adds a definition of
panic_fmt()
which endlessly loops; this isn't ideal (a better solution is probablty to write to stderr or syslog) - Adds a piece of code to support exeption handling which does nothing
- Defines a
main()
method suitable for calling from libc, which does nothing when used in release mode. This is to make it possible to compile the code. - Defines a
main()
method that handles bridging to C and then forwards to atest()
method - Defines a stub
test()
function, which you can replace with logic to test your code
Now you're reading to go. Just write normal functions and code. To make a function usable, it will need to be pub
and #[no_mangle]
.
For example, a really simple function might be:-
This could then be used as a LLVM JIT plugin by looking up the function simple_plugin
as:-
extern crate predicator;
use *;
Functions can also make use of anything defined in the core
crate. Be wary of using anything in the libc
crate, as LLVM JIT plugins can be used with statically-linked code and so libc functions and global statics may not have been linked in to the program using your plugin. This caveat does not apply when running the plug in directly to test it.
Function can take arguments and return results, eg this plugin:-
Can then be used like this:-
let binary_plugin_function_pointer = orcJitStack..expect;
// Execute the function
let size = 20;
let some_array = ;
let result = unsafe ;
assert!;
Be aware that you are crossing the equivalent of a 'C' boundary. The predicator framework can not prevent you from not catching panic!, passing Box
values, mismatching types, etc. It is recommended that you stick to very simple structures and primitives. More complexity will work, but it is extremely hard to debug when something breaks. There is nothing to stop you using types from other no_std
crates, but you should avoid importing global (or thread local) statics from them. Defining global statics and thread local statics in the plugin code should be fine, however.
Building
To build the LLVM JIT plugin, use:-
NOTE: We need to check if -C relocation-model=static
is needed
NOTE: The switch -C lto
should not actually be needed if your Cargo.toml
is correctly set up.
You can find the output inside wherever cargo
has defined the target folder. If you've forked this crate, you'll find it at .cargo/target/x86_64-unknown-linux-musl/release/deps/NAME_OF_CRATE-HEX_RANDOM_VALUE.bc
where NAME_OF_CRATE
is the name of your crate and RANDOM_VALUE
is the value of -C metadata=RANDOM_VALUE -C extra-filename=-RANDOM_VALUE cargo passes as part of the build. An example path might be
.cargo/target/x86_64-unknown-linux-musl/release/deps/experiment_with_ffi-805d16cbb3e10aad.bc`. When cargo builds it produces build output that contains a hint to this path:-
Compiling experiment-with-ffi v0.0.0 (file:///Volumes/Source/GitHub/lemonrock/experiment-with-ffi)
Running `rustc --crate-name experiment_with_ffi src/lib.rs --crate-type bin --emit=dep-info,link -C opt-level=3 -C panic=abort -C lto --emit=llvm-bc -C metadata=24221fe0742db2e8 -C extra-filename=-24221fe0742db2e8 --out-dir /Volumes/Source/GitHub/lemonrock/experiment-with-ffi/.cargo/target/x86_64-unknown-linux-musl/release/deps --target x86_64-unknown-linux-musl -C ar=x86_64-linux-musl-ar -C linker=x86_64-linux-musl-cc -L dependency=/Volumes/Source/GitHub/lemonrock/experiment-with-ffi/.cargo/target/x86_64-unknown-linux-musl/release/deps -L dependency=/Volumes/Source/GitHub/lemonrock/experiment-with-ffi/.cargo/target/release/deps`
Finished release [optimized] target(s) in 0.25 secs
In this scenario, NAME_OF_CRATE
is experiment-with-ffi
and RANDOM_VALUE
is 24221fe0742db2e8
, seen above as -C metadata=24221fe0742db2e8 -C extra-filename=-24221fe0742db2e8
Alternative build approaches
Debug mode
To build in debug mode use:-
To check the LLVM IR code the plugin is created from
To check the generated LLVM IR, use:-
This code is not built in debug mode, as it becomes very difficult to read. If you want to build it in debug mode, omit the --release
switch above.
Stripping Release Mode Code
By default, the LLVM IR and bit code generated by Rust's compiler contains some additional debug information even when generated with --release
. This can be removed using the opt
program.
To removeit from IR code (.ll
files), do the following:-
and from bit code (.bc
files):-
Note the absence of the -S
switch.
Interestingly, the generated .ll
code can sometimes be smaller than the .bc
code. I've observed as much as 24%.
Thanks
With thanks to the tutorial at https://github.com/jauhien/iron-kaleidoscope#chapter-3-optimizer-and-jit-support
Licensing
The license for this project is AFGPL-3.0.