131. Traits

The plug, again

In chapter 90 you met Viscosity’s plugin interface in TypeScript:

interface LanguagePlugin {
  id: string;
  extensions: string[];
  lower(source: string): LoweredModule;
  emit(...): string;
}

Any object with those members is a LanguagePlugin. Nobody has to say so: TypeScript compares shapes. That is structural typing, and it is why a plain object literal can be passed as a plugin.

Rust needs the same idea, a set of methods that many types can provide. It is called a trait, and it differs in one way that you will feel immediately.

Declaring and implementing

Here is a cut-down plugin trait, adapted from the real one in engine/rust/crates/core/src/plugin.rs:

trait Plugin {
    fn id(&self) -> &str;
    fn exts(&self) -> &[&str];

    fn handles(&self, f: &str) -> bool {
        for e in self.exts() {
            if f.ends_with(e) {
                return true;
            }
        }
        false
    }
}

id and exts end with ;: they are required, and each type writes its own. handles has a body: it is a default method, and every implementing type gets it for free (a type may still override it). Now two plugins:

struct Js;
struct Py;

impl Plugin for Js {
    fn id(&self) -> &str { "javascript" }
    fn exts(&self) -> &[&str] {
        &[".js", ".mjs"]
    }
}

Py is the same with "python" and &[".py"]. With that, Js.id() and Py.handles("b.py") work like any method from chapter 127. Leave out a required method and the impl is rejected: error[E0046]: not all trait items implemented, missing: lower.

Membership is declared

Give a type an id method of its own, without the impl, and ask for a Plugin:

struct Rb;
impl Rb {
    fn id(&self) -> &str { "ruby" }
}
show(&Rb);  // show(p: &dyn Plugin)

Rust 1.97 (trimmed):

error[E0277]: the trait bound
  `Rb: Plugin` is not satisfied
help: the trait `Plugin` is not
  implemented for `Rb`

Having a method called id means nothing. Two traits can both have an id with different meanings, and the impl block is where a type says which promise it is keeping. That is nominal typing.

There is a fairness rule too: you may write impl Trait for Type only if you defined the trait or the type in your own crate. You can make your types Display, or give Vec your trait, but you can’t make Vec Display: that would be two outsiders deciding for both. The Rust book calls this the orphan rule^[1].

Traits you already used

{:?} works on Option and Vec because they implement the standard Debug trait, and {} works on numbers and strings because they implement Display. When you write #[derive(Debug, Clone, PartialEq)] above a struct, the compiler writes those impls for you. You can also write one. The Rust port of Viscosity makes its error type printable like this (from plugin.rs):

struct CompileError(String);

impl fmt::Display for CompileError {
    fn fmt(&self, f: &mut fmt::Formatter)
        -> fmt::Result {
        f.write_str(&self.0)
    }
}

Now println!("{}", e) prints the message. The standard library calls your fmt. That is the other half of what traits are for: letting code written long ago call code written today.

dyn: one variable, many types

A list of plugins holds a Js and a Py, which are different types of different sizes. A Vec needs one element type. The answer is a trait object: &dyn Plugin, “a reference to some type that implements Plugin, I won’t say which”.

let ps: Vec<&dyn Plugin> =
    vec![&Js, &Py];
for p in &ps {
    if p.handles("b.py") {
        println!("{}", p.id());
    }
}

trait Plugin {
    fn id(&self) -> &str;
    fn exts(&self) -> &[&str];
    fn handles(&self, f: &str) -> bool {
        for e in self.exts() {
            if f.ends_with(e) {
                return true;
            }
        }
        false
    }
}

struct Js;
struct Py;

impl Plugin for Js {
    fn id(&self) -> &str {
        "javascript"
    }
    fn exts(&self) -> &[&str] {
        &[".js", ".mjs"]
    }
}

impl Plugin for Py {
    fn id(&self) -> &str {
        "python"
    }
    fn exts(&self) -> &[&str] {
        &[".py"]
    }
}

fn main() {
    let ps: Vec<&dyn Plugin> =
        vec![&Js, &Py];
    for f in ["a.mjs", "b.py", "c.rb"] {
        let mut who = "none";
        for p in &ps {
            if p.handles(f) {
                who = p.id();
            }
        }
        println!("{} -> {}", f, who);
    }
    use std::mem::size_of;
    let one = size_of::<&Js>();
    let two = size_of::<&dyn Plugin>();
    println!("{} {}", one, two);
}

How does p.id() know which id to run? The reference carries a second pointer. Step through it:

let ps: Vec<&dyn Plugin> =
    vec![&Js, &Py];
for p in &ps {
    println!("{}", p.id());
}

On this machine &Js is 8 bytes and &dyn Plugin is 16: the second word is the vtable pointer. The run above prints both.

Compare it with JavaScript. plugin.lower(src) in the TypeScript engine is a property lookup by name, and V8 makes it fast with an inline cache that remembers the shapes it has seen (chapter 64). A dyn call never looks anything up by name. The compiler knew every method of the trait, so it numbered them and built each vtable ahead of time; at run time the call reads a fixed slot. What it can’t know is which vtable it will get, so the call is indirect, and the Rust book notes that this keeps the compiler from inlining the method^[1]. Chapter 132 shows the other way to call a trait method.

Your turn

trait Layout {
    // where element i's field f lives
    fn slot(&self, i: usize, f: usize)
        -> usize;
}

// nf fields per element
struct Aos {
    nf: usize,
}

// n elements per column
struct Soa {
    n: usize,
}

impl Layout for Aos {
    fn slot(&self, i: usize, f: usize)
        -> usize {
        todo!()
    }
}

impl Layout for Soa {
    fn slot(&self, i: usize, f: usize)
        -> usize {
        todo!()
    }
}

fn read(l: &dyn Layout, buf: &[f64],
    i: usize, f: usize) -> f64 {
    todo!()
}

trait Layout {
    fn slot(&self, i: usize, f: usize)
        -> usize;
}

struct Aosoa {
    nf: usize,
    b: usize,
}

impl Layout for Aosoa {
    fn slot(&self, i: usize, f: usize)
        -> usize {
        todo!()
    }
}

What you learned

• A trait is a named set of methods. Types sign up with impl Trait for Type, writing the required methods and inheriting the default ones.
• Traits are nominal: a matching method isn’t enough. And the orphan rule says you must own the trait or the type.
• Debug, Display, Clone and PartialEq are traits; derive writes their impls.
• A trait object, &dyn Trait, is a fat pointer: data plus a vtable of function pointers. Calls through it are dynamic dispatch.
• drip-rs collects roots of many types through &[&dyn Trace].