Rust Workshop

The workshop is divided into two parts of roughly the same length.

The first part is structured as a tutorial where we go through the basics of Rust and its tooling, some of the more important and non-obvious language features, and a few items from the ecosystem that might be interesting, including a generic serialization/deserialization library, a command-line argument parser, a server-side web framework, and a client-side web framework.

The second part is a hands-on, guided coding session, where we will try to build a fairly simple, yet functional feed reader webapp. We will start by defining the server-side API, and if time permits, we might conclude with a browser-based WebAssembly client.

The canonical way of installing Rust is using rustup, a helper program that takes care of downloading the various components of the infrastructure for building Rust programs.

Rust is also packaged for many operating systems, but the compiler is updated and released in a regular fashion, and these packages are usually at least slightly out of date. In general, you want to have a way of getting your hands onto as recent version of the compiler as possible.

As a bonus, rustup allows you to have multiple versions of the compiler installed on the system, as well as seamless switching between them on demand. This is useful if you want to play around with, e.g., the nightly builds of the compiler.

…in which we write the proverbial archeprogram.

Each Rust binary has an entry point called main. Main usually returns the "unit" type (i.e. "nothing", void).

We print stuff to stdout in Rust using one of two macros: print! or println!. These are macros, among other reasons, due to one significant limitation of Rust: the lack of support for variadic functions.

Since this is our first contact with Rust, here's the program in its entirety:

fn main() {
  println!("Hello, World!");
}

Cargo is the standard build and dependency management tool for Rust. It takes care of:

• fetching and compiling the dependencies (both internal and external) of your project;
• building your project;
• creating distributable packages for your project (and optionally uploading them to the public).

(Do exercise 1.)

Cargo "packages" are called "crates". By default, Cargo will create a "binary" crate; to create a "library" crate, you can pass --lib to cargo init. A crate can generate both binaries and a library at the same time by tweaking the configuration file by hand.

The vast majority of Cargo configuration is done through the Cargo.toml file in the project root. This will list your dependencies, the files in the project you would like to build, and some basic metainformation about the crate.

(Do exercises 2 and 3.)

Rust has a rich set of tools to help you write code that works across data types. Generics allow us to write code which will work with any data type. For example, we can implement the Either data type:

enum Either<L, R> {
  Left(L),
  Right(R),
}

fn main() -> () {
  // the compiler can infer the type for "R", but has no way of infering it
  // for "L", thus we have to annotate explicitly.
  let a : Either<&str, u32> = Either::Right(42);

  // the compiler can infer the type for "L", but has no way of infering it
  // for "R", thus we have to annotate explicitly.
  let b : Either<&str, u32> = Either::Left("Error.");
}

// we can also destructure within `if`s with `if let`
if let Either::Right(result) = a {
  // "result" is now == 42
}

// of course, `match` shines here...
let end_result = match a {
  Either::Left(_)  => -1,    // `_` is a convention for "discard this value"
  Either::Right(t) => t / 2, // `end_result` would be 21
};

The vast majority of container types in the standard library are generic. Vectors are std::vec::Vec<T>, hashmaps are std::collections::HashMap<K, V>, etc.

Rust performs "monomorphization" of generic code, i.e. it generates code with concrete types at compile time, eliminating runtime overhead.

Traits are a feature that allows us to inform the compiler of shared functionality between a set of types in an abstract way. In other words, it's how Rust supports ad-hoc polymorphism, and it's one of the most pervasive and powerful mechanisms of abstractions in the language.

Conceptually, traits are equivalent to type classes in Haskell or concepts in C++. They share some common ground with the idea of interfaces in other object-oriented languages.

Traits allow us, among other things, to constrain the behavior of generic parameters in our code.

// defining traits
trait Addressable {
    fn get_address(&self) -> String;
}

struct Contact {
    name: String,
    address: String,
}

// implementing traits
impl Addressable for Contact {
    fn get_address(&self) -> String { self.address.clone() }
}

// constraining type parameters to certain traits
fn send<T: Addressable>(what: T) -> () {
    ship_to(what.get_address());
}

// equivalent to (arguably more readable):
fn send2<T>(what: T) -> () where T: Addressable {
    ship_to(what.get_address());
}

// iterators in Rust are simply objects that implement a certain trait...
trait Iterator {
    // "Item" is called a "placeholder type". It is used to avoid using
    // generic type parameters which can be implemented multiple times for a
    // single object, making method resolution ambiguous.
    type Item;
    fn next(&mut self) -> Option<Self::Item>;
}

struct AnIterator {}

impl Iterator for AnIterator {
    type Item = u32;

    fn next(&mut self) -> Option<Self::Item> {
        return Some(42);
    }
}

Previously, we have written the Either type which can serve well to represent a computation that can either succeed (returning Either::Right(T)) or fail (returning Either::Left(E)). It turns out this is a very powerful construct that powers the primary error handling mechanism in the Rust ecosystem: it is available, and prominently used in the standard library.

In the Rust standard library, this type is called std::result::Result<T, E>; it's so important, however, that it's included in the "Rust prelude", a list of things that get imported by default into every Rust program.

Instead of the slightly confusing left/right convention, the Result type is an enum of two more appropriately named variants: Ok(T) or Err(E).

Result has a slightly weaker cousin, std::option::Option, also in the prelude, which – instead of representing computations that either produce a value or an error – denotes an optional value. Its variants are Some(T) or None, and the APIs between the two types are very similar.

fn fac(n: u32) -> Result<u32, String> {
  if n > 20 { return Err(String::from("n too large.")); }
  Ok((1..=n).fold(1, |acc, x| acc * x))
}

fn main() -> () {
  // these types have a very rich API
  let t = fac(21).map(|factorial| factorial / 2);
  if let Ok(end_result) = t {
    println!("{}", t);
  }

  // unwraps the `Result`, panics with the error message in case it's an Err.
  println!("{}", t.expect("Unable to calculate the factorial:"));

  // you can convert between `Result` and `Option` (and vice-versa)
  let opt_t : Option<u32> = fac(10).ok();
}

No programming language in the "systems" category can avoid interfacing with C. Rust can interact equally well with C in both directions: when calling C code from Rust (through its FFI interface), and when calling Rust code from C.

Rust comes with two "standard" libraries built-in:

• libcore, and
• libstd.

libcore is heap allocation-free, platform-agnostic, and depends on a handful of symbols like memcpy and memset. It lives in the core::* namespace.

When writing code for embedded systems, it's usual (and often necessary) to only import libcore, and avoid the use of the higher-level libstd, something that's popularly called no_std in the Rust community. There are numerous consequences to this, most notably the fact that many 3rd party crates depend on libstd. When crates do support no_std, this is usually explicitly mentioned in the documentation.

libstd is the "standard" standard library of Rust that we've been using so far – it defines various portable, but platform-dependent features and types like I/O, multithreading, containers etc. It lives in the std::* namespace.

Rust imports a reasonable number of often-used standard library features implicitly into every crate. This is called the Rust Prelude, and it's the reason we can use Vec, Result, Option et al. without importing them explicitly.

An important caveat is that the WebAssembly target has a separate "standard" library, and basically falls into the no_std category.

Rust includes basic built-in support for writing unit tests. These can be inline with your library/module files, or in a separate tests/ directory. It has support for basic assertions, and cargo includes a test runner which makes executing tests easy.

fn make_ordinal(nums: &Vec<i32>) -> Vec<String> {
    let to_ordinal = |x: &i32| {
      let x_str = x.to_string();
      let suffix =
          if x_str.ends_with("1") { "st" }
          else if x_str.ends_with("2") { "nd" }
          else if x_str.ends_with("3") { "rd" }
          else { "th" };

      format!("{}{}", x_str, suffix)
    };

    nums.iter().map(to_ordinal).collect()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_ordinals() {
        let v = vec![1, 32, 3, 0];
        let exp = vec![
            String::from("1st"),
            String::from("32nd"),
            String::from("3rd"),
            String::from("0th"),
        ];
        assert_eq!(make_ordinal(&v), exp);
    }
}

Rust generates binaries with full symbol metadata, thus any native debugger should do. GDB got native support for debugging Rust programs with version 7.12, and LLDB is reported to work well.

Rust itself comes with two wrapper scripts, rust-lldb and rust-gdb, which load some handy pretty printers.

Sometimes (particularly in a safe language which doesn't segfault often), an easy alternative to debugger is printing. In Rust, there is Debug trait which allows any type to be converted into string. Together with derive macros, is is trivial to implement Debug for the most of the types. Alongside the Debug trait, there is dbg! macro which offers quite convenient way to print results.

Rust is seriously targeting WebAssembly as one of its core platforms.

There are two main approaches to WebAssembly: the stdweb approach, and the wasm-bindgen approach. They significantly differ in their philosophies, approach to interop, and community adoption.

There are certain degrees of compatibility between these two projects, i.e. they are not necessarily mutually exclusive.

The Rust ecosystem for asynchronous programming is very rich, although temporarily slightly fragmented.

One of the first serious attempts at bringing async I/O to Rust is Tokio. Tokio builds on top of the futures crate, bringing an ecosystem of executors and reactors for futures.

In the meantime, the community has started a process of stabilization of Rust futures, bringing them into the standard library. This has been rooted in the work made by the futures crate, but has some significant (and incompatible) changes to the API.

Tokio has support for std::future, but it's only available as an alpha release.

async-std is a new attempt at bringing foundational async building blocks to Rust, and stands in "competition" with Tokio. std::futures are a first-class citizen.

async and await are new additions to the Rust syntax which will become available in the upcoming version of the compiler (most probably 1.39). They are syntax sugar on top of standard std::future APIs, allowing us to write more synchronous-looking code.

In-depth discussion of asynchronous programming is out of the scope of this workshop, but it's important to keep the distinction between these subtly incompatible libraries and concepts in mind when browsing through the ecosystem.

Serde is a serialization/deserialization framework for Rust with a very wide support for data formats, and a focus on high performance. The most obvious target for serde is JSON (through the serde_json crate), but TOML, MessagePack, YAML, Python's pickle, and many others are well-supported.

Rust's standard data types and data structures are covered by serde out of the box, meaning you can trivially serialize from and deserialize into, e.g., hashmaps and vectors. A derive macro is provided for simple generation of serialization and deserialization traits in arbitrary structs.

For highly customized cases, or cases not covered by the out-of-the-box functionality, implementing the traits "by hand" is also supported.

Serde is widely accepted by the Rust community, and a lot of crates defining custom data types (e.g. the uuid crate) provide serde support. It provides no_std support, with some obvious caveats like the lack of support for data types which feature heap allocation.

use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Debug)]
enum Genre {
    Crunk,
    Ghettotech,
    // variants can have parameters
    Other(String),
    // another option:
    // Other { name: String },
    Powerviolence,
    Psychobilly,
    Zeuhl,
}

#[derive(Serialize, Deserialize, Debug)]
struct Album {
    artist: String,
    title: String,
    year: u16,
    genre: Genre,
}

fn main() -> () {
    let album = Album {
        artist: String::from("Nick Cave & The Bad Seeds"),
        title: String::from("Ghosteen"),
        year: 2019,
        genre: Genre::Other(String::from("Sad")),
    };

    let album_serialized = serde_json::to_string(&album).expect("Unable to serialize");
    println!("{}", album_serialized);
    // {"artist":"Nick Cave & The Bad Seeds","title":"Ghosteen","year":2019,"genre":{"Other":"Sad"}}

    let album_obj : Album = serde_json::from_str(&album_serialized).expect("Unable to deserialize");
    println!("{:?}", album_obj);
    // Album { artist: "Nick Cave & The Bad Seeds", title: "Ghosteen", year: 2019, genre: Other("Sad") }
}

actix is a generic actor framework for Rust, and actix-web is a high-performance HTTP/web framework for Rust written on top.

There are other projects bringing a high-performance HTTP layer to Rust, but they mostly suffer from various drawbacks like building only with the nightly version of the compiler (Rocket) or being too low-level (hyper).

Actors are a first class citizen in actix-web, and allow for a nice abstraction over asynchronous computation.