RustBLR

https://talks.dhruvin.dev/rustblr

What is this book

This book contains slides and links of talks I presented at Rust Bangalore.

Each top level chapter is a subject of talk-series, and each chapter below is a subject of talk.

Slides alone may not be sufficient to understand the subject in question as they are created to accompany the presentation. There are references at the end of most slides that expand further into the subject.

Why mdbook

mdbook was chosen as it allows syntax highlighting, editable examples that run on rust playground, and testing if the examples compile and/or run correctly. It also allows me to add corrections or extensions later.

Licenses

• Code: MIT or Apache-2.0
• Prose: CC-BY-SA-4.0

Rust FFI

Origin story

Have you ever wondered how Rust can interoperate with other programming languages? Me neither! Well, that was until I worked on a pluggable authentication module that needed to talk to libpam.

What to expect

The talk-series explores Rust FFI (Foreign Function Interface) ecosystem. FFI allows Rust code to interoperate with code from various programming languages that speak well defined ABI (Application Binary Interface).

The talk-series assumes familiarity with Rust functions, types, and statics. It will mostly present unsafe code, and ways to make safe(r) abstractions. It is intended for Rust library authors.

External Blocks

• Part of the Rust language
• Foundational to Rust's FFI story
• Provide declarations of items that are not defined in the current crate
  • functions
  • statics

Examples

extern "C" {
    // functions and statics go here
}

References

• https://doc.rust-lang.org/reference/items/external-blocks.html#external-blocks
• https://doc.rust-lang.org/rust-by-example/std_misc/ffi.html

Functions

• Patterns in parameters are disallowed
• Must not have body

Examples

use std::ffi::*;

extern "C" {
    /// writes the string s and a trailing newline to stdout
    fn puts(s: *const c_char) -> c_int;
}

fn main() {
    let s = CString::new("Hello, RustBLR!").unwrap();
    assert!(unsafe { puts(s.as_ptr()) } >= 0);
}

References

• https://doc.rust-lang.org/reference/items/external-blocks.html#functions
• https://doc.rust-lang.org/nomicon/ffi.html#calling-foreign-functions

Statics

• Declared without the initializer expression
• Both immutable and mutable access are unsafe as it may have uninitialized or invalid value

Examples

use std::ffi::*;

extern "C" {
    /// index of the next element to be processed in argv by getopt
    static optind: c_int;
}

fn main() {
    assert_eq!(unsafe { optind }, 1);
}

Caveats

• An immutable static must be initialized before any Rust code is executed

References

• https://doc.rust-lang.org/reference/items/external-blocks.html#statics
• https://doc.rust-lang.org/nomicon/ffi.html#accessing-foreign-globals

ABI

Cross-platform ABIs

• extern "Rust": Default for regular rust function declarations
• extern "C": Default for extern block function declarations
• extern "system": "C", but for Win32 on x86_32 it's stdcall

Platform-specific ABIs

Non-exhaustive list:

• extern "cdecl"
• extern "stdcall"
• extern "win64"
• extern "sysv64"
• extern "aapcs"
• extern "fastcall"
• extern "vectorcall"
• extern "thiscall"
• extern "efiapi"

Examples

// Same as extern "C" { }
extern { }

References

• https://doc.rust-lang.org/stable/reference/items/external-blocks.html#abi
• https://doc.rust-lang.org/nomicon/ffi.html#foreign-calling-conventions

Variadic Functions

• Declared variadic by specifying ... as the last argument

Examples

use std::ffi::*;

extern "C" {
    /// print formatted output
    fn printf(format: *const c_char, ...) -> c_int;
}

fn main() {
    let format = CString::new("Hello, %s!").unwrap();
    let arg = CString::new("RustBLR").unwrap();
    assert_eq!(unsafe { printf(format.as_ptr(), arg.as_ptr()) }, 15);
}

Caveats

• Needs least one parameter before variadic parameter
• Normal Rust functions can not be variadic

References

• https://doc.rust-lang.org/stable/reference/items/external-blocks.html#variadic-functions
• https://doc.rust-lang.org/nomicon/ffi.html#variadic-functions

Link

• Attributes that control the behaviour of a external block
  • link
    • name: required if kind is specified
    • kind
      • dylib: default
      • static
      • framework: macos
      • raw-dylib: windows
    • modifiers
      • +bundle: static
      • -whole-archive: static
      • -verbatim
    • wasm_import_module: env
    • import_name_type: windows
  • link_name
  • link_ordinal: windows

Examples

use std::ffi::*;

#[link(name = "c", kind = "dylib")]
extern "C" {
    #[link_name = "puts"]
    fn log(s: *const c_char);
}

#[cfg(target_family = "wasm")]
#[link(wasm_import_module = "foo")]
extern {
    // ...
}

fn main() {
    let s = CString::new("Hello, RustBLR!").unwrap();
    unsafe {
        log(s.as_ptr());
    }
}

References

• https://doc.rust-lang.org/stable/reference/items/external-blocks.html#the-link-attribute
• https://doc.rust-lang.org/nomicon/ffi.html#linking

Bindgen

• Maintained by rust-lang
• De facto interface
• Partial support for C++ and Objective C
• Uses libclang internally

Examples

extern crate bindgen;
fn example() {
bindgen::builder()
    .header("wrapper.h")
    .generate()
    .expect("could not generate bindings");
}

References

• https://rust-lang.github.io/rust-bindgen
• https://crates.io/crates/bindgen
• https://docs.rs/bindgen

Build Script

• use platform- and architecture-specific headers
• cargo install --build bindgen
• wrapper.h
  • #include
  • replacements
• build.rs
  • .parse_callbacks(Box::new(bindgen::CargoCallbacks))
• include!(concat!(env!("OUT_DIR"), "/bindings.rs"))
• #![allow(<lint>)]

References

• https://doc.rust-lang.org/cargo/reference/build-scripts.html

Header

• header
• header_contents

Examples

extern crate bindgen;
bindgen::builder()
    .header("wrapper.h");

extern crate bindgen;
bindgen::builder()
    .header_contents("wrapper.h", "#include <lib.h>");

References

• https://docs.rs/bindgen/latest/bindgen/struct.Builder.html

Filter

Allow/Block

• kinds
  • file
  • function
  • type
  • var
  • item
• allowlist_*
  • recursively
• blocklist_*

CodegenConfig

• with_codegen_config
  • functions
    • ignore_functions
  • types
  • vars
  • methods
    • ignore_methods
  • constructors
  • destructors

Examples

extern crate bindgen;
bindgen::builder()
    .header_contents("wrapper.h", "#include <time.h>")
    .allowlist_function("time");

/* automatically generated by rust-bindgen 0.69.4 */

pub type time_t = ::std::os::raw::c_long;
extern "C" {
    pub fn time(arg1: *mut time_t) -> time_t;
}

extern crate bindgen;
bindgen::builder()
    .header_contents("wrapper.h", "#include <getopt.h>")
    .with_codegen_config(bindgen::CodegenConfig::VARS);

/* automatically generated by rust-bindgen 0.69.4 */

pub const no_argument: u32 = 0;
pub const required_argument: u32 = 1;
pub const optional_argument: u32 = 2;
extern "C" {
    pub static mut optarg: *mut ::std::os::raw::c_char;
}
extern "C" {
    pub static mut optind: ::std::os::raw::c_int;
}
extern "C" {
    pub static mut opterr: ::std::os::raw::c_int;
}
extern "C" {
    pub static mut optopt: ::std::os::raw::c_int;
}
extern "C" {
    pub static mut optreset: ::std::os::raw::c_int;
}

References

• Builder::allowlist_*
• Builder::blocklist_*
• CodegenConfig

Derive

• derive_copy
  • no_copy
• derive_debug
  • impl_debug
  • no_debug
• derive_default
  • no_default
• derive_hash
  • no_hash
• derive_partialord
• derive_ord
• derive_partialeq
  • impl_partialeq
  • no_partialeq
• derive_eq

Examples

extern crate bindgen;
bindgen::builder()
    .header_contents("wrapper.h", "#include <time.h>")
    .derive_default(true)
    .allowlist_type("timespec");

/* automatically generated by rust-bindgen 0.69.4 */

pub type time_t = ::std::os::raw::c_long;
#[repr(C)]
#[derive(Debug, Default, Copy, Clone)]
pub struct timespec {
    pub tv_sec: time_t,
    pub tv_nsec: ::std::os::raw::c_long,
}

// <layout_tests>

References

• Builder::derive_*
• Builder::impl_*

Callbacks

• rerun-if-env-changed for used env variables
  • SOURCE_DATE_EPOCH
• rerun-if-changed for included header files
  • wrapper.h

Examples

extern crate bindgen;
bindgen::builder()
    .header("wrapper.h")
    .parse_callbacks(Box::new(bindgen::CargoCallbacks::new()));

cargo:rerun-if-env-changed=TARGET
cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS
cargo:rerun-if-changed=wrapper.h

References

• Builder::parse_callbacks
• ParseCallbacks
• CargoCallbacks

Include

• include!(concat!(env!("OUT_DIR"), "/bindings.rs"));

Examples

#![allow(non_upper_case_globals)]
#![allow(non_camel_case_types)]
#![allow(non_snake_case)]

include!(concat!(env!("OUT_DIR"), "/bindings.rs"));

References

• include!
• concat!
• env!
• OUT_DIR
• There is no cross-platform way to use include_*!

Rust Error

What to expect

The talk-series explores various mechanisms for error handling in Rust.

The talk-series assumes familiarity with Rust traits, and derive macros. It is intended for Rust library and application authors.

Primer

Traits

• Debug
• Display
• Error

Derive Macros

• Debug

core::fmt::Debug

pub trait Debug {
    // Required method
    fn fmt(&self, f: &mut Formatter<'_>) -> Result;
}

• format trait for {:?} and {:#?}
• should format the output in a programmer-facing, debugging context
• prefer #[derive(Debug)] over impl Debug
• {var:?} prints inline, {var:#?} prints pretty

Examples

#[derive(Debug)]

#[derive(Debug)]
struct Point {
    x: i32,
    y: i32,
}

let origin = Point { x: 0, y: 0 };

assert_eq!(
    format!("The origin is: {origin:?}"),
    "The origin is: Point { x: 0, y: 0 }",
);

assert_eq!(format!("The origin is: {origin:#?}"), "The origin is: Point {
    x: 0,
    y: 0,
}");

impl Debug

use std::fmt;

struct Point {
    x: i32,
    y: i32,
}

impl fmt::Debug for Point {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Point")
            .field("x", &self.x)
            .field("y", &self.y)
            .finish()
    }
}

let origin = Point { x: 0, y: 0 };

assert_eq!(
    format!("The origin is: {origin:?}"),
    "The origin is: Point { x: 0, y: 0 }",
);

assert_eq!(format!("The origin is: {origin:#?}"), "The origin is: Point {
    x: 0,
    y: 0,
}");

Caveats

• unstable output
• infallible formatting
• fallible writing

References

• trait:core::fmt::Debug
• derive:core::fmt::Debug
• struct:core::fmt::Formatter
• fn:core::fmt::Formatter::debug

core::fmt::Display

pub trait Display {
    // Required method
    fn fmt(&self, f: &mut Formatter<'_>) -> Result;
}

• format trait for {}
• user-facing output, cannot derive
• implements ToString, prefer Display
• internationalization, only one impl

Examples

impl Display

use std::fmt;

struct Point {
    x: i32,
    y: i32,
}

impl fmt::Display for Point {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "({}, {})", self.x, self.y)
    }
}

let origin = Point { x: 0, y: 0 };

assert_eq!(format!("The origin is: {origin}"), "The origin is: (0, 0)");

References

• trait:core::fmt::Display
• trait:alloc::string::ToString

core::error::Error

pub trait Error: Debug + Display {
    // Provided methods
    fn source(&self) -> Option<&(dyn Error + 'static)> { ... }
}

impl dyn Error + 'static {
    pub fn is<T: Error + 'static>(&self) -> bool { ... }
    pub fn downcast_ref<T: Error + 'static>(&self) -> Option<&T> { ... }
    pub fn downcast_mut<T: Error + 'static>(&mut self) -> Option<&mut T> { ... }
}

• concise lowercase sentences without trailing punctuation
• Error::source when errors cross “abstraction boundaries”

Examples

Error::source

use std::{error::Error, fmt};

#[derive(Debug)]
struct SuperError {
    source: SuperErrorSideKick,
}

impl fmt::Display for SuperError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "SuperError is here!")
    }
}

impl Error for SuperError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        Some(&self.source)
    }
}

#[derive(Debug)]
struct SuperErrorSideKick;

impl fmt::Display for SuperErrorSideKick {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "SuperErrorSideKick is here!")
    }
}

impl Error for SuperErrorSideKick {}

fn get_super_error() -> Result<(), SuperError> {
    Err(SuperError { source: SuperErrorSideKick })
}

fn main() {
    match get_super_error() {
        Err(e) => {
            println!("Error: {e}");
            println!("Caused by: {}", e.source().unwrap());
        }
        _ => println!("No error"),
    }
}

References

• trait:core::error::Error
• impl dyn Error + 'static

thiserror

Derive Macros

• Error

Attributes

• #[error("...")]
• #[source]
• #[from]
• #[error(transparent)]

#[error("...")]

• inside format string:
  • #[error("{var}")]
  • #[error("{0}")]
• as format string arg:
  • #[error("{}", .var)]
  • #[error("{}", .0)]

Examples

Arguments

use thiserror::Error;

#[derive(Error, Debug)]
pub enum Error {
    #[error("first letter must be lowercase but was {:?}", first_char(.0))]
    WrongCase(String),
    #[error("invalid index {idx}, expected at least {} and at most {}", .limits.lo, .limits.hi)]
    OutOfBounds { idx: usize, limits: Limits },
}

References

• thiserror

#[source]

• to identify underlying cause
• field marked #[source] or is named source

Examples

Source

#[derive(Error, Debug)]
pub struct MyError {
    msg: String,
    #[source]  // optional if field name is `source`
    source: anyhow::Error,
}

Caveats

• source must implement Error or Deref<Target = dyn Error>

References

• thiserror

#[from]

• impl From generated for each variant that contains a #[from]
• #[from] implies #[source]

Examples

From

#[derive(Error, Debug)]
pub enum MyError {
    Io(#[from] io::Error),
    Glob(#[from] globset::Error),
}

Caveats

• variant with #[from] must not contain any other fields beyond the source error

References

• thiserror

#[error(transparent)]

• forwards the Error::source and Display::fmt to #[source]

Examples

Anything else

#[derive(Error, Debug)]
pub enum MyError {
    ...

    #[error(transparent)]
    Other(#[from] anyhow::Error),  // source and Display delegate to anyhow::Error
}

Hide implementation detail

// PublicError is public, but opaque and easy to keep compatible.
#[derive(Error, Debug)]
#[error(transparent)]
pub struct PublicError(#[from] ErrorRepr);

impl PublicError {
    // Accessors for anything we do want to expose publicly.
}

// Private and free to change across minor version of the crate.
#[derive(Error, Debug)]
enum ErrorRepr {
    ...
}

References

• thiserror

Dhruvin Gandhi

contact@dhru.vin