206 lines
7.4 KiB
Org Mode
206 lines
7.4 KiB
Org Mode
* effers
|
|
ergonomic effect handlers in rust
|
|
|
|
** how to use
|
|
*** defining effects
|
|
effects are defined with traits
|
|
|
|
#+begin_src rust
|
|
trait Printer {
|
|
fn print(&self, s: &str);
|
|
fn available() -> bool;
|
|
}
|
|
trait Logger {
|
|
fn debug(&mut self, s: &str);
|
|
fn info(self, s: &str);
|
|
}
|
|
#+end_src
|
|
|
|
functions can take ~self~, ~&self~, ~&mut self~, or no ~self~ parameter. at this point ~self~ parameters with a specified type (like ~self: Box<Self>~) are not supported
|
|
|
|
*** defining a program
|
|
|
|
programs are defined as a normal function, with the added ~program~ attribute, which specifies (optional) a name for the program, and (required) the list of effects and corresponding functions that are used
|
|
|
|
#+begin_src rust
|
|
#[effers::program(MyCoolProgram =>
|
|
Printer(print(&self) as p, available as printer_available),
|
|
Logger(debug(&mut self), info(self))
|
|
)]
|
|
fn my_program(val: u8) -> u8 {
|
|
if printer_available() {
|
|
p("hey hi hello");
|
|
}
|
|
|
|
debug("this is a debug-level log");
|
|
info("this is a info-level log");
|
|
|
|
val + 3
|
|
}
|
|
#+end_src
|
|
|
|
**** name
|
|
|
|
the first token (~MyCoolProgram~) will be the name of the program. this is optional, and can be skipped:
|
|
|
|
#+begin_src rust
|
|
#[program(
|
|
Printer(print(&self) as p, available as printer_available),
|
|
Logger(debug(&mut self), info(self))
|
|
)]
|
|
#+end_src
|
|
|
|
if skipped, the default name will be the program function's name (~my_program~) in PascalCase (~MyProgram~)
|
|
|
|
**** listing effects
|
|
effects are listed by writing the trait's name, followed by a parenthesized list of the functions that will be used
|
|
|
|
***** listing effect functions
|
|
|
|
due to limitations of proc-macros, it's unknown what kind of ~self~ parameter the function takes, if any, and so it has to be explicitly specified (if you have ideas on how to fix this, please open a PR!): here's how each type is specified:
|
|
|
|
- ~fn print();~: ~print~
|
|
- ~fn print(self);~: ~print(self)~
|
|
- ~fn print(mut self);~: ~print(self)~
|
|
- ~fn print(&self);~: ~print(&self)~
|
|
- ~fn print(&mut self);~: ~print(&mut self)~
|
|
|
|
***** effect function aliases
|
|
functions can be given an alias using the ~as~ keyword (~print(&self) as p~) so that the function can be called by a different name inside the program
|
|
|
|
*** defining effect handlers
|
|
effect handlers are defined by declaring a struct, and implementing the corresponding trait on it
|
|
|
|
#+begin_src rust
|
|
struct IoPrinter;
|
|
impl Printer for IoPrinter {
|
|
fn print(&self, s: &str) {
|
|
println!("{}", s)
|
|
}
|
|
fn available() -> bool {
|
|
true
|
|
}
|
|
}
|
|
|
|
struct FileLogger;
|
|
impl Logger for FileLogger {
|
|
fn debug(&mut self, s: &str) {
|
|
println!("debug: {}", s)
|
|
}
|
|
fn info(self, s: &str) {
|
|
println!("info: {}", s)
|
|
}
|
|
}
|
|
#+end_src
|
|
|
|
*** running programs
|
|
programs are run by providing the corresponding handlers *in the order listed in the program definition*, and finally calling the ~run~ method, providing it the required parameters
|
|
|
|
#+begin_src rust
|
|
let result: u8 = MyCoolProgram.add(IoPrinter).add(FileLogger).run(3);
|
|
assert_eq!(result, 6);
|
|
#+end_src
|
|
|
|
** examples
|
|
- [[./examples/main.rs][main: general use case]]
|
|
- [[./examples/clone.rs][clone: how cloning and copying programs works]]
|
|
- [[./examples/module.rs][module: effects from other modules are supported]]
|
|
|
|
** performance
|
|
running programs in effers is *really* fast. i'll first explain the reasoning why, and then i'll show benchmarks in case you don't believe me :)
|
|
|
|
*** explanation
|
|
the macro replaces every call to an effect function to be a call to the corresponding trait, and since it uses generics, the type is known at compile time and therefore there is no dynamic dispatch. for example, the program in the [[./examples/module.rs][module example]] ends up being the following:
|
|
|
|
#+begin_src rust
|
|
impl<A: inc::Incrementer> ProgWithIncrementer<A> {
|
|
fn run(mut self, val: u8) -> u8 {
|
|
let x = <A as inc::Incrementer>::increment(&self.1, val);
|
|
let y = <A as inc::Incrementer>::increment(&self.1, x);
|
|
x + y
|
|
}
|
|
}
|
|
#+end_src
|
|
|
|
note: this is literally the output of ~cargo expand~, you can try it yourself!
|
|
|
|
when running the program with ~Prog.add(inc::TestInc).run(1)~, rust fully knows at compile time that the ~increment~ effect function is from the trait ~Implementer~, and it's being called on ~TestInc~. since all of this is known at compile time, rust can perform all normal optimizations, and the cost of using effers is practically none
|
|
|
|
*** benchmarks
|
|
note: i do not know how to properly benchmark libraries, so if you think what i did is not correct, please feel free to open an issue/PR. i followed the example showcased in [[https://www.youtube.com/watch?v=0jI-AlWEwYI][Alexis King's Effects for Less talk]], which /should/ properly test the actual effect system's cost on programs. i recommend you look at that talk if you haven't already, as it's highly informative, and it explains why this benchmark makes sense. the tldw is that when benchmarking effect systems, we want to know the performance cost of using the effect system, we don't care about benchmarking the effects themselves, and so we need simple effects so that the cost of the system is appreciable in comparison
|
|
|
|
the test is run with input of 20 and 20000
|
|
|
|
the benchmark compares an implementation using =effers=:
|
|
|
|
#+begin_src rust
|
|
#[program(State(get(&self), put(&mut self)))]
|
|
fn prog() -> u32 {
|
|
loop {
|
|
let n = get();
|
|
if n <= 0 {
|
|
return n;
|
|
} else {
|
|
put(n - 1);
|
|
}
|
|
}
|
|
}
|
|
#+end_src
|
|
|
|
with a plain-rust implementation:
|
|
|
|
#+begin_src rust
|
|
fn prog(mut n: u32) {
|
|
let r = loop {
|
|
if n <= 0 {
|
|
break n;
|
|
} else {
|
|
n = n - 1;
|
|
}
|
|
};
|
|
assert_eq!(0, r);
|
|
}
|
|
#+end_src
|
|
|
|
the following are the results:
|
|
|
|
#+begin_src
|
|
state: effers: 20 time: [319.18 ps 319.78 ps 320.34 ps]
|
|
change: [-0.9133% -0.6671% -0.4224%] (p = 0.00 < 0.05)
|
|
Change within noise threshold.
|
|
Found 2 outliers among 100 measurements (2.00%)
|
|
2 (2.00%) high mild
|
|
|
|
state: effers: 20000 time: [320.23 ps 320.64 ps 321.02 ps]
|
|
change: [-0.0515% +0.2343% +0.5306%] (p = 0.11 > 0.05)
|
|
No change in performance detected.
|
|
Found 18 outliers among 100 measurements (18.00%)
|
|
13 (13.00%) low mild
|
|
3 (3.00%) high mild
|
|
2 (2.00%) high severe
|
|
|
|
state: no effect system: 20
|
|
time: [319.94 ps 321.22 ps 323.39 ps]
|
|
change: [-0.5255% -0.1001% +0.3816%] (p = 0.69 > 0.05)
|
|
No change in performance detected.
|
|
Found 12 outliers among 100 measurements (12.00%)
|
|
8 (8.00%) low mild
|
|
1 (1.00%) high mild
|
|
3 (3.00%) high severe
|
|
|
|
state: no effect system: 20000
|
|
time: [319.41 ps 319.85 ps 320.27 ps]
|
|
change: [-2.4698% -1.9813% -1.5456%] (p = 0.00 < 0.05)
|
|
Performance has improved.
|
|
Found 2 outliers among 100 measurements (2.00%)
|
|
2 (2.00%) high mild
|
|
#+end_src
|
|
|
|
now, i might be wrong about this, but it seems that there is no extra cost incurred by using effers :)
|
|
|
|
im pretty sure that that is wrong, and that the compiler is doing some extra optimizations i am not aware of. again, if you know how to improve this benchmark, please let me know
|
|
|
|
*** building a program
|
|
|
|
there might be some performance cost in *building* a program before running it, since it uses the builder pattern and a bunch of functions have to be called, but the benchmarks above show it's not an appreciable difference
|