Course 1: Rust Language

Rust Introduction: Cargo, Crates, Rust project, Hello Word, (2h on computers),

Pierre Cochard, Tanguy Risset

Why should computer science engineer always learn new languages?

Nowadays, Rust use is growing exponentially, the number of library and project using or useful to Rust developpers is already huge. The reason for that it that Rust provides safe memory management without a garbage collector, ensuring both performance and security. Its ownership system eliminates data races and segmentation faults. It enables efficient concurrent programming while guaranteeing memory safety. It is associated with a powerful modern ecosystem and and it is suited for embedded systems, system programming as well as high-performance applications. Adopted by major industry players, Rust is emerging as a reliable alternative for secure and system-level development.

`cargo` is not only a compiler, it manages many aspects that you need to understand to use Rust correctly:

• Dependency Management: Cargo manages the dependencies of a Rust project. It automatically downloads and builds the required libraries and dependencies, making it easier for developers to include external code in their projects.

• Project Configuration: Cargo uses a file called Cargo.toml to configure a Rust project. This file includes information about the project, its dependencies, and various settings.

• Building and Compilation: Cargo handles the compilation process of Rust code. It can build the project, manage dependencies, and generate executable binaries. Developers can use Cargo commands like cargo build to compile the project or cargo run to build and run it in one step.

• Testing: Cargo provides built-in support for testing Rust code. Developers can use the cargo test command to run tests defined in the project.

• Documentation: Cargo can generate and serve documentation for the project using the cargo doc command. This is useful for both internal and external documentation (the HTML file that you are reading has been generated by cargo doc)

• Publishing Packages: Cargo facilitates the process of publishing Rust packages to the official package registry, called "Crates.io." This makes it easy for others to discover and use Rust libraries and projects.

As your can check on the Rust Standard Library documentation : println! is not a function, it is a macro.

Macros are called with a trailling bang (such as println!), they are a way of writing code that writes other code, which is known as metaprogramming. Understanding and declaring Macros is quite complex and will be seen later. But using them (such as using println!) is usually very easy.

let x = 5;
println!("The value of x is: {x}");
x = 6;
println!("The value of x is: {x}");

#![allow(unused)]
fn main() {
let x = 5;
{
    let x = x + 1;
    {
        let x = x * 2;
        println!("The value of x in the inner scope is: {x}");
    }
}
println!("The value of x is: {x}");
}

fib(0)=1
fib(1)=1
fib(i)=fib(i-1)+fib(i-2)  for i >= 

#![allow(unused)]
fn main() {
struct Complex {
    re: f32,
    im: f32,
}

fn build_complex(re: f32,im:f32)->  Complex {
    Complex {re,im}
}       

let mut a = build_complex(2.3,4.0);
println!("a=({},{})",a.re,a.im);
a.re = a.re+1.;
println!("a=({},{})",a.re,a.im);
}

As templates in C++, Rust enables the use of generic type in function or struct, enums or methods definitions. Here is a simple definition of a Point structure using integer or float coordinates:

#![allow(unused)]
fn main() {
struct Point<T> {
    x: T,
    y: T,
}

let integer = Point { x: 5, y: 10 };
let float = Point { x: 1.0, y: 4.0 };
}

A trait defines a functionality that a particular type has and can share with other types. Traits are similar to a feature often called interfaces in other languages.

Many natural methods can be defined for any -- or at least many -- types. For instance the copy or clone methods (rust primitives) or the fmt method (of the trait std::fmt::Display, rust standard library) that enables to use println!. These methods are not defined by default when a new type is defined.

Traits are defined by the trait keyword. By convention they are named starting with an upper case, e.g. the trait Clone, it usually defines a method with the same name in lower case (here: clone())

If you want to clone a Complex, you juste have to write the implementation of the clone method:

impl Clone for Complex {
    fn clone(&self) -> Self{
        Complex{re: self.re, im: self.im}
    }
     // Now a.clone() can be used on Complex variables
}

For certain traits³: (Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default, etc.), the compiler is capable of providing basic implementations for some traits via the #[derive] attribute (In Rust, an attribute is metadata applied to code elements like functions, structs, modules, or crates, attributes are prefixed with # and enclosed in square brackets []).

These traits can still be manually implemented if a more complex behavior is required.

for instance, the Clone trait can be automatically derived for Complex type:

#[derive(Clone)]
struct Complex {
    re: f32,
    im: f32,
}

[... no need to implement Clone ...]

let a = build_complex(2.3,4.0);
let _c=a.clone()

[...]

In Rust, move semantics refers to the ownership transfer of data from one variable to another. Rust enforces a strict ownership model where each piece of data has a single owner at a time, and ownership can be transferred (or "moved") when a value is assigned to another variable or passed as an argument to a function.

By default an assignement such as let y = x implies a transfer of ownership of the content of x to y. This ownership concept will be studied further in next course. This limit side effects: modifying y do not modify x.

In order to dupplicate the cube (as it would be done in any language), one has to clone it or to implement the Copy trait. Deriving the Copy trait for Cube changes the semantic of the assignement: the assignement is now a copy, not a move.

Course 2: Rust Language

Ownership, borrowing, mutability, heap and stack in Rust (2h on computers)

Pierre Cochard, Tanguy Risset

Ownership is a set of rules that govern how a Rust program manages memory. All programs have to manage the way they use a computer's memory while running. Some languages have garbage collection that regularly looks for no-longer-used memory as the program runs; in other languages, the programmer must explicitly allocate and free the memory.

Rust uses a third approach: memory is managed through a system of ownership with a set of rules that the compiler checks.

If any of the rules are violated, the program won't compile. None of the features of ownership will slow down your program while it's running.

Because ownership is a new concept for many programmers, it does take some time to get used to. When you understand ownership, you'll have a solid foundation for understanding the features that make Rust unique.

Here are the Ownership Rules:

• Each value in Rust has an owner.

• There can only be one owner at a time.

• When the owner goes out of scope, the value will be dropped.

The scope notion is (for the moment) the same as in traditional languages such as C.

    #[derive(Debug, Clone, Copy)]
    struct Cube {
        c: f32,
    }

    fn main() {
        let x = [Cube{c:0.5},Cube{c:0.75},Cube{c:1.0}];
        let y = x;
        println!("x is: {:?}", x);
        println!("y is: {:?}", y);
    }

    fn main() {
        let x = [(10,20),(30,40),(50,60)];
        let y = x;
        println!("x is: {:?}", x);
        println!("y is: {:?}", y);
    }

References in Rust are equivalent to references in any language: a pointer to the same content, except that, because of the strong static verifications performed by the compiler, a reference is always guaranteed to point to a valid value of a particular type for the life of that reference¹.

References are indicated by the ’&’ operator. As in C, the opposite of referencing is dereferencing, which is accomplished with the dereference operator: ’*’. However, in practice, the ’&’ operator can be omitted; this is called deref coercion or autoderef (it is implemented in a trait Deref that is implemented for all references).

This autoderef is implemented in almost all cases, except when you assign a value to a dereferenced mutable reference:

    let mut x = 10;
    let y = &mut x;

    *y = 20; //explicit dereferencing is required here

Ownership in Rust means having full control over a value (here a value is to be understand as L-value, i.e. a value which is stored in a memory box). The owner is responsible for managing the value's lifetime (we will talk later about lifetimes) and cleaning up its resources when it goes out of scope. Ownership can be transferred (moved) but is unique at any given time (except in very special cases that we will see).

Borrowing (via references, either &T or &mut T) allows you to access a value without transferring ownership. Immutable borrow (&T): Grants read-only access to a value. Mutable borrow (& mut T): Grants exclusive, write-access to a value.

Rules of Mutable References:

• You can only have one mutable reference to a value at a time.

• While a mutable reference exists, no other references (mutable or immutable) to the same value are allowed.

    #[derive(Debug)]
    struct Cube {
        c: f32,
    }

    fn double(y : &mut Cube) {
        y.c = 2.*y.c;
     }
     

    fn main() {
        let mut x = Cube { c: 0.75 };
        let y = &mut x;
        double(y);
        println!("My cube is: {:?}", x);
        println!("My cube is: {:?}", y);    
    }

    #[derive(Debug)]
    struct Cube {
        c: f32,
    }

    fn double(y : &mut Cube) {
        y.c = 2.*y.c;
     }
     

    fn main() {
        let mut x = Cube { c: 0.75 };
        let y = &mut x;
        double(y);
        println!("My cube is: {:?}", y);
        println!("My cube is: {:?}", x);    
    }

       let s1 = String::from("hello"); 
       let s2 = s1;

(a)                        (b)

(a) before call       (b) during call                   (c) after call 

Course 2: Rust Language

Advanced types Compound and collection types

Pierre Cochard, Tanguy Risset

'Tuples' are fixed-size collections of arbitrary-typed values, they are defined with the (Type, Type, ...) syntax:

#![allow(unused)]
fn main() {
// Explicit type:
let mut tup: (i32, i32, f32, &str) = (31, 16, 47.27, "hello!"); 

// Inferred type:
let mut tup = (31, 16, 47.27, "hello!"); 
}

Accessing individual values within a Tuple can be done by either:

• referring to its index
• destructuring the tuple and bind it to individually-named variables:

#![allow(unused)]
fn main() {
let mut tup = (31, 16, 47.27, "hello!"); 

// Access by index:
tup.0 = 22;
tup.3 = "world!";

// 'Destructuring' a tuple:
let (t0, t1, t2, t3) = tup;
println!("y = ({t1}, {t2})");
}

let mut tup = (31, 16, 47.27, "hello!"); 

// The function's prototype (to be implemented):
fn mul2(t: &mut f32);

mul2(...);

assert!(tup == (31, 16, 94.54, "hello!"));

Tuples can be conviently used in a function in order to return multiple values, which can then be assigned to distinct variables in a same expression:

#![allow(unused)]
fn main() {
// A function returning a pair of signed integers:
fn return_tuple(x: i32) -> (i32, i32) {
    return (x+1, x+2);
}

// Calling a function, and storing its result:
let y: (i32, i32) = return_tuple(8);
println!("y = {:?}", y);
println!("y = ({:?}, {:?})", y.0, y.1);

// Passing a tuple as an argument to a function:
fn print_tuple(x: &(i32, i32)) {
    println!("x = ({:?}, {:?})", x.0, x.1);
}

print_tuple(&y);
}

#![allow(unused)]
fn main() {
// The function prototype to be implemented:
fn swap(tup: &mut(i32, i32));

let mut x = (31i32, 27i32);
swap(&mut x);

assert!(x == (27i32, 31i32));
}

Arrays are fixed-size groups of values of the same type, and can be defined in Rust with the syntax:

• [Subtype; Length], for instance [i32; 10]

#![allow(unused)]
fn main() {
// Explicit type:
let a: [i32; 3] = [31, 16, 47];

// Inferred type:
let b = [0, 1, 2, 3, 4]; // #[i32; 5]

// Create and zero-initialize an array:
let mut a: [usize; 10] = [0; 10];
// same as:
let mut a = [0 as usize; 10];
// same as:
let mut a = [0usize; 10];

// Writing at a specific index:
// Note: in Rust, as in C, array indices start at 0
a[0] = 2;
println!("a[0] = {}", a[0]);
}

As in most programming languages, multidimensional/nested arrays are also supported in rust, and can be declared as follows:

#![allow(unused)]
fn main() {
// 2-dimensional array, 2 arrays of `i32` with a length of 10 each:
let mut multi_array = [[0 as i32; 10]; 2];
}

#![allow(unused)]
fn main() {
let a1 = [(1, 2), (3, 4), (5, 6)];
let a2 = [(1, 2), (3, 4), (5, (6, 7))];
}

Arrays are convenient for storing and processing a set of contiguous data on the stack, for instance through the use of loops, ranges and iterators.

A range represents an interval of values between a start and an end point. In rust, they can be conveniently used with the start..end construct (here excluding the end value), or with start..=end (here including the end value).

let a = 0..10;
let b = 1..=10;

// 'a' range:
assert!(a.contains(&0));
assert!(!a.contains(&10));

// 'b' range:
assert!(!b.contains(&0));
assert!(b.contains(&10)); 

// The 'a' and 'b' ranges have the same number of elements:
assert_eq!(a.count(), b.count());

Iterators allow to go through an array, a range or a collection, and access each element one-by-one.

#![allow(unused)]
fn main() {
let r = 0..10;
// Iterate over a range:
for n in r.into_iter() {
    print!("{n} ");
    // -> 0 1 2 3 4 5 6 7 8 9
}
println!();

// Iterate over an array:
let mut a = [0; 10];

// Basic for-loop iteration:
for x in a {
    println!("{x}");
}
// From a 'range':
for n in (0 .. a.len()) {
    println!("{}", a[n]);
}
// As mutable, changing the values of the array:
for x in &mut a {
    *x += 1;
}
// Equivalent to (using a 'closure'):
a.iter_mut().for_each(|x| *x += 1 );

// Iterate with both element and index:
for (i, x) in a.iter_mut().enumerate() {
    *x += i;
}
}

#![allow(unused)]
fn main() {
let mut multi_array = [[0 as i32; 10]; 2];

// The following must be true:
assert_eq!(multi_array, [
    [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
    [10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
]);
}

'Vectors' are a collection of multiple values of a same type stored on the heap. Unlike arrays, they have a dynamic size: they can grow, or shrink.

A Vec object has ownership over the data located in its underlying heap-allocated buffer, which means that the buffer will be deallocated whenever the owning object goes out of scope.

#![allow(unused)]
fn main() {
// The easiest way to create a vector is to use the 'vec!()' macro:
let mut v = vec![0, 1, 2, 3, 4, 5]; // Vec<i32>
println!("Value: {:?}", v);

// 'Pushing' (appending) a new value at the end:
v.push(6);
println!("Value: {:?}", v);

// 'Popping' (removing) its last value:
let last = v.pop();
println!("Last value: {:?}, Vector: {:?}", last, v);
}

#![allow(unused)]
fn main() {
let mut v0: Vec<i32> = vec![0, 1, 2, 3, 4];
// get a pointer to the underlying heap memory buffer:
let v0_ptr: *const i32 = v0.as_ptr();

// Create another vec 'v1' from 'v0', and get its heap pointer again:
let mut v1: Vec<i32> = v0;
let v1_ptr = v1.as_ptr();

// Create another vec 'v2' from 'v1':
let mut v2: Vec<i32> = v1.clone();
let v2_ptr = v2.as_ptr();
}

#![allow(unused)]
fn main() {
// Assertion A: the address of pointer 'v0' is the same as pointer 'v1'
assert_eq!(v0_ptr.addr(), v1_ptr.addr());

// Assertion B: the address of pointer 'v1' is the same as pointer 'v2'
assert_eq!(v1_ptr.addr(), v2_ptr.addr());

// Assertion C: the address of pointer 'v0' is the same as pointer 'v2'
assert_eq!(v0_ptr.addr(), v2_ptr.addr());
}

Iterating over a vector is the exact same process as for an array (most operations are inter-compatible!).

#![allow(unused)]
fn main() {
// Initializing from a range and iterator:
let mut v = Vec::from_iter((0..6).map(|i| i+1 ));
println!("Value: {:?}", v);

// Iterate/increment:
for x in &mut v {
    *x += 1;
}
println!("Value: {:?}", v);
// General operations:
v.rotate_left(1);
println!("Value: {:?}", v);
// etc.
}

#![allow(unused)]
fn main() {
let mut v = vec![0, 1, 2, 3, 4, 5];
let mut a = [0; 6];

(...)

assert_eq!(v, vec![]);
assert_eq!(a, [5, 4, 3, 2, 1, 0]);
}

HashMap are heap-allocated collections of same-type values indexed by a unique key. Like vectors, they can grow, or shrink. They make a convenient choice for representing indexes, dictionaries, or any other type of database-like objects:

#![allow(unused)]
fn main() {
// Unlike Vec, the HashMap data structure need to be explicitly included!
use std::collections::HashMap;

// Inferred type:
let mut departments = HashMap::new(); // HashMap<i32, str>
departments.insert(85, "Vendée");
departments.insert(31, "Haute-Garonne");
departments.insert(44, "Loire-Atlantique");

// We use the ampersand(&) and the key (&1) as the argument 
// because [..] returns us a reference of the value. It is not the actual value in the HashMap.
let d31 = departments[&31];
assert_eq!(d31, "Haute-Garonne");

// Removing a key:
departments.remove(&85);

// Iterating over all values:
for department in departments {
    // We get a tuple!
    println!("Key: {}, Value: {}", department.0, department.1);
}
}

#![allow(unused)]
fn main() {
use std::collections::BTreeMap;

let vec = vec![
    ("Y. Horigome", 281),
    ("N. Huston", 279),
    ("M. Dell", 153),
    ("J. Eaton", 281),
    ("S. Shirai", 278),
    ("K. Hoefler", 270),
    ("C. Russell", 211),
    ("R. Tury", 273),
];

let mut map = BTreeMap::new();

[...]

for score in map {
    println!("{:?}", score);
}
}

(153, ["M. Dell"])
(211, ["C. Russell"])
(270, ["K. Hoefler"])
(273, ["R. Tury"])
(278, ["S. Shirai"])
(279, ["N. Huston"])
(281, ["Y. Horigome", "J. Eaton"])

The str primitive type can be used to represent a string literal:

#![allow(unused)]
fn main() {
// String literal:
let s = "Hello, World!";
}

As a literal, a str has a static lifetime which can be also explicitly stated in its type declaration. A static lifetime means that the object is valid throughout the entire duration of the program.

#![allow(unused)]
fn main() {
// Here, the three syntaxes are equivalent:
let s = "Hello, World!"; // Inferred type & lifetime
let s: &str = "Hello, World!"; // Explicit type, inferred lifetime
let s: &'static str = "Hello, World!"; // Explicit type & lifetime
}

Unlike const char* in the C programming language, &str in Rust is not null-terminated, but relies on a slice, which is composed of a pointer and a size in bytes:

#![allow(unused)]
fn main() {
let s = "Hello, World!";
println!("Pointer: {:?}, Length: {} bytes", s.as_ptr(), s.len());

for (n, char) in s.chars().enumerate() {
    println!("Char {n}: {char}");
}
}

For safety reasons, Rust doesn't allow modifying the actual contents (the characters) of a &str, thus the following does not compile:

#![allow(unused)]
fn main() {
let s: &mut str = "Hello, World!";
}

#![allow(unused)]
fn main() {
let s1 = "It's not about the bunny      \t"; 

// Remove leading/trailing whitespace, tabs and newlines from 's1': 
let s2 = s1.trim();
println!("{s1}");
println!("Address: {:?}, Length: {}", s1.as_ptr(), s1.len());
println!();
println!("{s2}");
println!("Address: {:?}, Length: {}", s2.as_ptr(), s2.len());
}

#![allow(unused)]
fn main() {
let s1 = "     It's not about the bunny      \t"; 
let s2 = s1.trim();
}

A String, on the other hand, is a standard library collection type that can be basically seen as a vector of char, dynamically stored on the heap. Just like a Vec, it can grow, shrink, and has ownership over its own underlying buffer, which makes it an easier object to manipulate. While it inherits all of the str methods, it does not have a static lifetime.

#![allow(unused)]
fn main() {
// Create from a string literal:
let mut s = String::from("Owls are not what they seem");

// Append a 'char':
s.push('!');
println!("Value: {:?}", s);

// Append another string:
s.push_str(" Really?");
println!("Value: {:?}", s);

// Other ways of appending to the String:
s = s + " Yes, ";
s += "really!";

// Iterate over every 'char'
for c in s.chars() {
    print!("{c} ");
}
println!("");

// Example of transformation:
s = s.chars().rev().collect();

println!("Value: {:?}", s);
}

#![allow(unused)]
fn main() {
let s0: &str = "That gum you like is going to come back in style";

// Build a 'String' object from the previous '&str':
let mut s1: String = String::from(s0);

// Now modify 'string':
s1 = s1.to_ascii_uppercase();
println!("{string}");

}

#![allow(unused)]
fn main() {
let s0: &str = "That gum you like is going to come back in style";

// Build a 'String' object from the previous '&str':
let mut s1: String = String::from(s0);
let s2: &str = s1.as_str();
}

A slice in rust can be considered as a bounded pointer or reference to a contiguous sequence of elements in an array, a collection, or a string of characters, as we saw earlier. It is declared with the &[T] syntax. Since it works like a reference, it does not have ownership over its contents.

#![allow(unused)]
fn main() {
// Create a byte buffer:
let mut buffer = [0 as u8; 16];

// Get a slice on half the buffer:
// (notice how the slice itself is not mutable, 
// but instead points to a mutable sequence in the buffer)
let slice: &mut[u8] = &mut buffer[0..8]; // we use the 'range syntax' here to capture the slice

// Iterate on the slice to change values:
for (i, n) in slice.iter_mut().enumerate() {
    *n = i as u8;
}
println!("{:?}", buffer);
}

#![allow(unused)]
fn main() {
let mut string = String::from("YOU REMIND ME TODAY OF A SMALL MEXICAN CHIHUAHUA");

let slice = ...;

slice.make_ascii_lowercase();

println!("{string}");
}

Course 1: Rust Language

Struct, enums, Traits and Object definitions

Pierre Cochard, Tanguy Risset

We have already seen the Struct concepts: Structs are similar to tuples in that both hold multiple related values. Unlike with tuples, in a struct you’ll name each piece of data so it’s clear what the values mean. Adding these names means that structs are more flexible than tuples: you don’t have to rely on the order of the data to specify or access the values of an instance.

Here is an example of Struct definition:

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

We create an instance by stating the name of the struct and then add curly brackets containing key: value pairs as for example:

    let user1 = User {
        active: true,
        username: String::from("someusername123"),
        email: String::from("someone@example.com"),
        sign_in_count: 1,
    };

To get a specific value from a struct, we use dot notation. For example, to access this user’s email address, we use user1.email. When creating instances from other instances The syntax .. specifies that the remaining fields not explicitly set should have the same value as the fields in the given instance.:

let user2 = User {
        email: String::from("another@example.com"),
        ..user1
    };

Unit struct (i.e. struct without fields) and Tuple struct (i.e. struct with no named fields) are special Rust features that might be useful in some cases (see https://practice.course.rs/compound-types/struct.html)

struct User {
    active: bool,
    username: &str,
    email: &str,
    sign_in_count: u64,
}

impl User {
    fn name(&self)->&String{
        &self.username
    }
}

As in C, Enum gives you a way of saying a value is one of a possible set of values. For instance, An IP address can be either an IPv4 address or an IPv6 address, but not both at the same time:

enum IpAddrKind {
    V4,
    V6,
}

This allows to store the two possible kind in "the same" memory location given that they will never be active together in one instance.

A new feature comparing to C is that we can put data directly into each enum variant.

enum IpAddr {
        V4(u8, u8, u8, u8),
        V6(String),
    }

    let home = IpAddr::V4(127, 0, 0, 1);

    let loopback = IpAddr::V6(String::from("::1"));

Rust has an extremely powerful control flow construct called match that allows you to compare a value against a series of patterns and then execute code based on which pattern matches. Pattern matching in an important area of computer science and compilation, we just show a very simple example here:

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

 enum Option<T> {
    None,
    Some(T),
}

fn some_function<T, U>(t: &T, u: &U) -> i32
where
    T: Display + Clone,
    U: Clone + Debug,
{

use std::fmt::Display;

struct Pair<T> {
    x: T,
    y: T,
}

impl<T> Pair<T> {
    fn new(x: T, y: T) -> Self {
        Self { x, y }
    }
}

impl<T: Display + PartialOrd> Pair<T> {
    fn cmp_display(&self) {
        if self.x >= self.y {
            println!("The largest member is x = {}", self.x);
        } else {
            println!("The largest member is y = {}", self.y);
        }
    }
}

#[derive(PartialEq,Clone,Debug)]
enum Paradigm {
    Functional,
    ObjectOriented,
}


#[derive(Clone,Debug)]
struct Language {
    name: &'static str,
    paradigms: Vec<Paradigm>,
    nb_users: i32,
}

impl Language {
    fn new(name: &'static str, paradigms: Vec<Paradigm>, nb_users: i32) -> Self {
        Language { name, paradigms, nb_users }
    }
}

let languages = vec![
    Language::new("Rust", vec![Paradigm::Functional,Paradigm::ObjectOriented], 100_000),
    Language::new("Go", vec![Paradigm::ObjectOriented], 200_000),
    Language::new("Haskell", vec![Paradigm::Functional], 5_000),
    Language::new("Java", vec![Paradigm::ObjectOriented], 1_000_000),
    Language::new("C++", vec![Paradigm::ObjectOriented], 1_000_000),
    Language::new("Python", vec![Paradigm::ObjectOriented, Paradigm::Functional], 1_000_000),
];

Course 2: Rust Language

Rust as a safe language: Pattern Matching, Handling Results/Errors, Options and Simple macros

Pierre Cochard, Tanguy Risset

The primary, and most explicit, use of pattern matching in Rust is done through the match statement, which can be perceived as the Rust-equivalent of a C switch, but with additional features. Its syntax is also a little bit different. For instance, let's take a look at this simple C program:

// C basic switch case:
enum Colors {
    Red, Blue, Green, Yellow, Orange
};

bool match_color_orange(Colors color) {
    switch (color) {
        case Orange: {
            printf("Orange!\n");
            return true;            
        }
        case Red:
        case Blue: {
            printf("Not orange :(\n"));
            return false
        }
        default: {
            printf("Still not orange\n");
            return false;
        }
    }
}

In Rust, we would have the following equivalent:

#![allow(unused)]
fn main() {
enum Colors {
    Red, Blue, Green, Yellow, Orange
}

fn match_color_orange(color: Colors) -> bool {
    match color {
        // 'case' statements are replaced by the
        // 'PATTERN => EXPRESSION' syntax:
        Colors::Orange => {
            println!("Orange!");
            true
        }
        // We use '|' operators here, instead of having 
        // multiple 'case' statements: 
        Colors::Red | Colors::Blue => {
            println!("Not orange :(");
            false
        }
        // Anything else (equivalent to 'default'):
        _ => {
            println!("Still not orange...");
            false
        }
    }
}
}

Once a pattern mach is found, the corresponding instruction are executed and the match instruction terminates (it does not check for other matching patterns, the first matching pattern is choosen). match statements can be directly bound to variables:

#![allow(unused)]
fn main() {
enum Colors { Red, Blue, Green, Yellow, Orange }

let color = Colors::Red;

let is_color_warm = match color {
    Colors::Orange => true,
       Colors::Red => true,
    Colors::Yellow => true,
                 _ => false
};
}

Matching ranges is also supported, for instance:

#![allow(unused)]
fn main() {
fn match_number(number: i32) {
    match number {
          50..=99 => println!("Between 50 and 99"),
       100..=1000 => println!("Between 100 and 1000"),
                _ => println!("Other value")
    }
}
}

And, as a matter of fact, any other type of expression can be matched! from string types:

#![allow(unused)]
fn main() {
fn match_str(s: &'static str) {
    match s {
        "Orange" => println!("Orange!"),
        "Yellow" => println!("Not orange"),
        _ => println!("Something else...")
    }
}
}

to other kinds of collections:

#![allow(unused)]
fn main() {
fn match_tup(tup: (i32, i32)) {
    match tup {
        (0, 0) => println!("Zeroes!"),
        (1, 1) => println!("Ones"),
        _ => println!("Something else...")
    }
}

match_tup((1, 1));
match_tup((0, 1));

fn match_array(arr: [u8; 3]) {
    match arr {
        [0, 1, 2] => println!("Array match!"),
                _ => println!("No match")
    }
}

match_array([0, 1, 2]);
match_array([4, 5, 6]);

fn match_slice(sl: &[i32]) {
    match sl {
        &[0, 1, 2] => println!("Slice matches!"),
                 _ => println!("No match")
    }
}

match_slice(&[0, 1, 2]);
}

As we saw earlier, the match statement can test any kind of value, and it also extends to custom and composite types, including struct instances. A custom struct can be indeed either matched by its contents in a very precise manner:

#![allow(unused)]
fn main() {
struct Point {
    x: isize,
    y: isize
}

let point = Point {x: 0, y: 100};

match point {
    // Only match Point if its 'x' member is equal to 0
    // and 'y' is equal to 100:
    Point {x: 0, y: 100} => println!("Match!"),
    _ => println!("No match!")
}
}

Or, in a more flexible way, using, for instance, ranges for its member values:

#![allow(unused)]
fn main() {
struct Point {
    x: isize,
    y: isize
}

let point = Point {x: 25, y: 100};
    
match point {
    // Only match if 'x' is between 0 and 100,
    // and 'y' is between 50 and 100
    Point {x: 0..=100, y: 50..=100} => println!("Match!"),
    _ => println!("No match!")
}
}

Finally, the _ => expression can be extended to any kind of value (or field value) that we want to ignore. This can also be done using the .. syntax, which will ignore all the following values or field values:

#![allow(unused)]
fn main() {
struct Point {
    x: isize,
    y: isize
}

let p = Point {x: 0, y: 100};
    
match p {
    // Only match if 'x' is between 0 and 100,
    // and ignore the 'y' field:
    Point {x: 0..=100, y: _} => println!("Match!"),
   // Only match if 'x' is between 101 and 1000,
    // Similarly, the '..' syntax will ignore all the struct fields after 'x':
    Point {x: 101..=1000, ..} => println!("Match!"),
    _ => println!("No match!")
}
}

Note: for compound/collection types, the .. syntax may be followed by other patterns:

#![allow(unused)]
fn main() {
let tup = (0, 1, 2, 3, 4);

match tup {
    // The first element of the tuple should be '0', and the last should be '4',
    // we ignore the values in-between:
    (0, .., 4) => println!("Match!"),
    _ => println!("No match")
}
}

#![allow(unused)]
fn main() {
fn match_slice(s: &[i32]) -> bool;

assert_eq!(match_slice(&[1, 20, 20, 30, 100]), false);
assert_eq!(match_slice(&[0, 5, 20, 30, 100]), false);
assert_eq!(match_slice(&[0, 10, 20, 30, 99]), false);
assert!(match_slice(&[0, 10, 20, 30, 40, 100]));
assert!(match_slice(&[0, 20, 20, 30, 50, 60, 70, 80, 90, 100]));
}

To handle and propagate runtime errors, Rust relies on a simple but efficient mechanism based on an enum: the Result<T, E> enum, which is defined as:

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E)
}
}

The templated T and E types have no trait implementation predicate whatsoever, they could be anything, for instance:

#![allow(unused)]
fn main() {
// This function returns a u8 slice if there is no error, a Vec<f32> if there is.
// This is probably not very useful, but it's still perfectly valid code:
fn my_function(i: i32) -> Result<&[u8], Vec<f32>> {...} 

// This too (empty tuple type for both):
fn my_function(i: i32) -> Result<(),()> {
    Ok(())
} 
}

The unwrap() method can be used to extract the Ok argument from a Result<...>. This will be explained in more detail further, but you will need it to test your function:

let u = my_function(3).unwrap(); 

An Error in Rust can be propagated down the call stack by using the ? syntax:

#![allow(unused)]
fn main() {
fn my_function(i: i32) -> Result<i32, ()> {...}

fn my_other_function() -> Result<i32, ()> {
    // Append the '?' operator right after the function call:
    let mut i = my_function(1)?;
    // Do something with 'i': 
    i += 1;
    // Return an 'Ok' result with the modified 'i' value:
    Ok(i)
}
}

Here, the my_function(1)? function call means:

• if the result enum value is Err (an error), then propagate the error now, by returning the same Err from my_function(), otherwise, continue with the rest of the code.

This code could also be implemented with an equivalent match statement, but is a bit more verbose:

#![allow(unused)]
fn main() {
fn my_other_function() -> Result<i32, ()> {
    let mut i = match my_function(1) {
        Ok(i) => i,
        Err() => return Err(())
    };
    i += 1;
    Ok(i)
}
}

// Your 'positive' function:
fn positive(i: i32) -> Result<i32, String> {...}

// Define a new function, and call 'positive(...)' from here:
fn check_positive() -> Result<i32, String> {
    ... // <- test positive & negative values here using the '?' syntax
}

// Check the return type from main:
fn main() {
    println!("{:?}", check_positive());
}

In general, returning with or without error from a main function, such as in the C or C++ programming languages, is done by returning an integer exit code (0 for success, error otherwise):

int main(void) {
    // No error, return 0:
    return 0;
}

In Rust, the main() function has no return type by default, and returning a i32 is not accepted by the compiler. For instance, the following code is invalid:

fn main() -> i32 {
    0
}

In this case, the compiler prints the following:

error[E0277]: `main` has invalid return type `i32`
 --> src/main.rs:3:14
  |
3 | fn main() -> i32 {
  |              ^^^ `main` can only return types that implement `Termination`
  |
  = help: consider using `()`, or a `Result`

The Termination trait documentation indeed indicates that only the following types are valid:

#![allow(unused)]
fn main() {
impl Termination for Infallible;
impl Termination for !;
impl Termination for ();
impl Termination for ExitCode;
impl<T: Termination, E: Debug> Termination for Result<T, E>;
}

Therefore, we can see that propagating a Result down to main() is possible, but is still a bit of a specific case. The type T held by the Ok enum value must implement the Termination trait, and the type held by the Err enum value must implement the Debug trait. For instance, the following still does not work because i32 does not implement the Termination trait:

fn main() -> Result<i32, String> {
    Ok(0)
}

But the following works:

// Using an empty tuple as the 'Ok' result:
fn main() -> Result<(), String> {
    Ok(())
}

// Or using the ExitCode type:
use std::process::ExitCode;

fn main() -> Result<ExitCode, String> {
    Ok(ExitCode::from(0))
}

fn positive(i: i32) -> Result<i32, String> {...}

fn check_positive() -> Result<i32, String> {...}

// Use a valid Result type here:
fn main() -> Result<?, ?>{
    // Call the 'check_positive' function here, and propagate its Result as the main() return type:
}

.unwrap(), .expect()

In some cases - when propagating an error is not possible, or unconvenient - dealing immediately with a Result type is preferrable. This is why certain methods, such as .unwrap() or .expect() are natively implemented, and quite commonly used:

• The .unwrap() method, for instance, will induce a panic! call and will exit the program immediately when encountering an error. Otherwise it will return the Ok value safely:

#![allow(unused)]
fn main() {
// Get the current working directory:
let dir: std::path::PathBuf = std::env::current_dir().unwrap();
println!("{:?}", dir);
}

• The .expect() method is really similar, but will allow the user to print a custom &str message on error, which will be prepended to the actual display of the Err contents:

#![allow(unused)]
fn main() {
fn my_function() -> Result<(), i32> {
    Err(1)
}
my_function().expect("Error! Now exiting program with error code");
}

• Other similar helper methods also exist, with different behaviors:
  • .unwrap_or(other: T) returns the value other in case of an Err
  • .unwrap_or_default() returns the type's default value in case of an Err
  • .unwrap_or_else(func: Fn) executes a custom function in case of an Err
  • etc.

panic!, assert! and other macros

In addition to Result types, other simple tools, in the form of macros, are provided:

• The panic!(msg) macro interrupts the program immediately and prints a custom error message:

fn main() {
    use std::io;
    // Read input from stdin:
    let mut buffer = String::new();
    println!("Please enter password:");
    io::stdin().read_line(&mut buffer).unwrap();
    // Panic if password is not long enough:
    if buffer.len() < 8 {
        panic!("Password should be at least 8 characters");
    } else {
        println!("{buffer}");
    }
}

• The assert!(bool), assert_eq!(lhs, rhs), and assert_ne!(lhs, rhs), verify a boolean statement or check equality between two elements:

fn main() {
    use std::io;
    // Read input from stdin:
    let mut buffer = String::new();
    println!("Please enter password:");
    io::stdin().read_line(&mut buffer).unwrap();

    // We assert that the password is at least 8 characters
    // This will cause a 'panic' if the assertion is false:
    assert!(buffer.len() >= 8, "Password should be at least 8 characters");

    // Here, we forbidden choosing 'password' as a password:
    assert_ne!(buffer.trim(), "password", "Choosing 'password' as password is unsafe.");
}

#![allow(unused)]
fn main() {
#[test]
fn password_test() {
    let pwd0 = String::from("pass");
    let pwd1 = String::from("password");
    let pwd2 = String::from("password!");
    let pwd3 = String::from("pass word!");
    let pwd4 = String::from("password!1");
    assert!(parse_password(&pwd0).is_err());
    assert!(parse_password(&pwd1).is_err());
    assert!(parse_password(&pwd2).is_err());
    assert!(parse_password(&pwd3).is_err());
    assert!(parse_password(&pwd4).is_ok());
}
}

The Option enum in Rust is somewhat similar to the Result enum, but its main purpose is to indicate the presence or absence of a value, rather than an error. It has the following definition:

#![allow(unused)]
fn main() {
pub enum Option<T> {
    None, 
    Some(T)
}
}

As an example, let's suppose we want to build a list of people to contact, with various information, such as the contact's name and address, and optionally phone number and/or e-mail, we could for instance define the following struct:

#![allow(unused)]
fn main() {
struct MyContact {
    name: &'static str,
 address: &'static str,
   email: Option<&'static str>,
   phone: Option<&'static str>,
}

let mut list: Vec<MyContact> = Vec::new();
list.push(MyContact {
       name: "Marlo Stanfield",
    address: "2601 E Baltimore St, Baltimore, MD 21224",
      email: None,
      phone: Some("+1 410-915-0909")
});
}

By doing this, we can then take advantage of the Option enum and pattern matching to decide of the best way to contact each person in the list:

#![allow(unused)]
fn main() {
for contact in list {
    match (contact.email, contact.phone) {
        // Both e-mail and phone are available:
        (Some(email), Some(phone)) => {
            if is_email_correct(email) {
                contact_by_email(email);
            } else {
                contact_by_phone(phone);
            }
        }
        // Only e-mail is available:
        (Some(email), None) => {
            contact_by_email(email);
        }
        // Only phone is available:
        (None, Some(phone)) => {
            contact_by_phone(phone);
        }
        // Neither phone nor email:
        (None, None) => {
            send_mail_to_address(contact.address);
        }
    }
}
}

As for the Result type, Option can be checked and handled immediately using the same .unwrap(), .expect() methods.

#![allow(unused)]
fn main() {
fn money_left() -> Option<i32>;
money_left().expect("No money left :(");
}

#![allow(unused)]
fn main() {
struct Book {
      name: String,
    author: String,
}

#[derive(Default)]
struct LibraryDatabase {
    books: Vec<Book>
}

impl LibraryDatabase {
    // The function to implement:
    fn search_book(&self, 
        name: Option<&'static str>, 
        author: Option<&'static str>
    ) -> Option<&Book> {...}
}
}

#![allow(unused)]
fn main() {
#[test]
fn test() {
    let mut database = LibraryDatabase::default();
    database.books.push(Book { name: String::from("Peter Pan"), author: String::from("Barrie")});

    assert!(database.search_book(Some("Peter Pan"), None).is_some());
    assert!(database.search_book(None, Some("Barrie")).is_some());
    assert!(database.search_book(None, None).is_none());
    assert!(database.search_book(Some("Barrie"), None).is_none());
    assert!(database.search_book(None, Some("Peter Pan")).is_none());
    assert!(database.search_book(Some("Alice in Wonderland"), Some("Barrie")).is_none());
    assert!(database.search_book(Some("Peter Pan"), Some("Lewis Carroll")).is_none());
}
}

Unlike attribute or derive macros, which must be defined in a separate crate, simple macros can be defined anywhere in our code, using the macro_rules! syntax:

#![allow(unused)]
fn main() {
macro_rules! hello_world {
    () => {
        println!("Hello World!")
    };
}

hello_world!();
}

Here, we defined a macro! that takes no argument, which is indicated by the () statement. Our hello_world!() macro call will be under the hood replaced by the contents that we defined within the => { ... } block.

Advantages of using macros

Our hello_world!() example is of course not very useful, and in fact adds unnecessary noise to a very simple piece of code, but think of the vec! macro for instance:

#![allow(unused)]
fn main() {
let v1 = vec![1, 2, 3, 4, 5];
let v2 = vec!();
let v3 = vec![1];
}

Defining the three different vectors by hand would actually mean writing the following code:

#![allow(unused)]
fn main() {
let v1 = <[_]>::into_vec(Box::new([1, 2, 3, 4, 5]));
let v2 = Vec::new<i32>();
let v3 = std::vec::from_elem(1, 1);
}

Notice how these three vectors are each time created in a very different way? In this case, the vec! macro allows defining a more practical and unified way of instantiating a Vec object, without having to remember all the (sometimes complex) underlying code. Furthermore, as you can see with this example, a macro! can also accept a variable number of arguments, which is not the case with a Rust function.

The different types of arguments (or fragment specifiers)

As you may already have guessed with our first basic macro example, which uses the => operator, macro_rules! relies on pattern matching to parse its arbitrary number of arguments.

macro_rules! can parse different kinds of patterns, including:

• (): the empty pattern, which means no argument (our previous example);
• block: a block expression, surrounded by { };
• expr: any kind of Rust expression;
• ident: an identifier (the name of a variable, function, etc.);
• literal: a number/string or other kind of litteral;
• etc. (see the full list here).

Matching a specific pattern

Let's now try an example with an actual argument. Here, we will use the ident designator in order to create functions from a simple macro call:

#![allow(unused)]
fn main() {
macro_rules! define_fn {
    ($fn_name:ident) => {
        fn $fn_name() {
            println!(
                "This function's name (ident) is: '{}()'.", 
                stringify!($fn_name)
            );
        }
    }
}
define_fn!(foo);
define_fn!(bar);
foo();
bar();
}

Let's break this code piece-by-piece:

#![allow(unused)]
fn main() {
($fn_name:ident) => {
}

  → Instead of an empty pattern (), we use the pattern ($fn_name:ident), in which $fn_name would be the name of the argument, and ident its type. The dollar sign ($) is used to declare a variable in the macro system that will contain the Rust code matching the pattern.

#![allow(unused)]
fn main() {
fn $fn_name() {
}

  → Within our generated code block, we declare a function with the name taken from our $fn_name ident argument.

#![allow(unused)]
fn main() {
println!(
    "This function's name (ident) is: '{}()'.", 
    stringify!($fn_name)
);
}

  → We then define the function's body, with a println! call, in which we print the ident's name using a utility macro called stringify!. This very useful macro will transform our $fn_name identifier into a &'static str object;

#![allow(unused)]
fn main() {
// All of this code should be generated by our new macro,
// but the name 'Foo' should be made variable:
struct Foo {
    print: &'static str
}
impl Foo {
    fn new() -> Foo {
        Foo { 
            print: "Foo" 
        }
    }
}
}

#![allow(unused)]
fn main() {
// The macro to implement:
macro_rules! define_struct { 
    ... 
}

// Use the following to verify that the macro is correct:
define_struct!(Foo);

let bar = Foo::new();
assert_eq!(bar.print, "Foo");
}

macro_rules! definitions can accept an arbitrary number of patterns, in a very simple way. Let's try it out on our define_fn! macro. We will add another pattern allowing to add arbitrary code expressions to the created fn:

#![allow(unused)]
fn main() {
macro_rules! define_fn {
    ($fn_name:ident) => {
        fn $fn_name() {
            println!(
                "This function's name (ident) is: '{}()'.", 
                stringify!($fn_name)
            );
        }
    }; // <-- pattern blocks must end with a semicolon if they're followed by other blocks
    
    // Our new pattern:
    ($fn_name:ident, $additional_code:expr) => {
        fn $fn_name() {
            println!(
                "This function's name (ident) is: '{}()'.", 
                stringify!($fn_name)
            );
            // Append the additional code 'expr' at the end of the defined fn:
            $additional_code
        }
    }
}
define_fn!(foo);
define_fn!(bar, println!("Additional code"));
foo();
bar();
}

Here, we added the ($fn_name:ident, $additional_code:expr) pattern, which is composed of two arguments: the same ident argument, followed by an expr argument, which can be any valid Rust expression. The two arguments are separated by a comma , but the choice of a comma is completely arbitrary, it could be (almost) any symbol.

Pattern matching for macro_rules! is quite different from pattern matching used in the match keyword. Macros can also easily deal with pattern repetition by using a special syntax, which resembles the one used for regular expressions. In particuler, the usual operators of regular expressions can be used: '_', '+' or '*' (one object, a repetition of objects -- at least one, a repetition of objects - possibly 0). In the following example, we want to replace the std::cmp::max() function to take an arbitrary number of arguments:

#![allow(unused)]
fn main() {
let mut max = std::cmp::max(1, 2);
max = std::cmp::max(max, 3);
max = std::cmp::max(max, 4);
max = std::cmp::max(max, 5);
}

In this case, having a macro like the following could prove useful, and would lighten the code a lot:

#![allow(unused)]
fn main() {
max!(1, 2, 3, 4, 5, 6*7, 3*4);
}

The way to do this is to use the $(...),+ syntax, as follows:

#![allow(unused)]
fn main() {
macro_rules! max {
    // Only one argument 'x', return 'x':
    ($x:expr) => {$x};
    // At least two arguments, 
    // - 'x' being the first,
    // - 'y' being one or more additional argument(s),
    // which is defined by the '$(...),+' syntax:
    ($x:expr, $($y:expr),+) => {
        // We recursively call 'max!' on the tail 'y'
        std::cmp::max($x, max!($($y),+))
    }
}
}

The + in the $($y:expr),+ syntax means one or more instances of the ($y) expression, separated by a comma ,.

Note: The * symbol also exists, and means zero or more instances of the pattern.

Now, if we were to call the max! macro the following way, we would only match the first pattern ($x:expr) => {$x}:

#![allow(unused)]
fn main() {
max!(1);
}

• With two arguments, we would match the second pattern ($x:expr, $($y:expr),+) with a single additional argument:

#![allow(unused)]
fn main() {
max!(1, 2); // expands to:
std::cmp::max(1, max!(2)); // expands to:
std::cmp::max(1, 2);
}

• And with more arguments recursively:

#![allow(unused)]
fn main() {
max!(1, 2, 3); // expands to:
std::cmp::max(1, max!(2, 3)); // expands to:
std::cmp::max(1, std::cmp::max(2, max!(3))); // expands to:
std::cmp::max(1, std::cmp::max(2, 3));
}

As a summary:

• $var captures a value in a pattern.
• $var:ident specifies a type (could be ident, expr, ty, etc.).
• $( $(var:pat),* or $( $(var:pat),+ captures repetitive sequences separated by commas.
• $var is replaced during macro expansion.

#![allow(unused)]
fn main() {
// Define the struct 'Foo':
define_struct!(
    name: Foo,
    members: {
        bar: i32
    }
    methods: {
        fn hello() {
            println!("hello!")
        }
        fn bar(&self) {
            println!("{}", self.bar);
        }
    }
);
// Instantiate the struct 'Foo':
let f = Foo::default();
// Call its bar method:
f.bar();
// Or its static 'hello' method:
Foo::hello();
}

#![allow(unused)]
fn main() {
// Define Foo struct:
define_struct!(
    name: Foo,
    members: {
        bar: i32
    }
    methods: {
        fn hello() {
            println!("hello!")
        }
        fn bar(&self) {
            println!("{}", self.bar);
        }
    }
);

// The define_struct! macro should define a new 'Foo!' macro,
// which allows copying the members and methods of 'Foo' into another new struct:
Foo!(FooCopy);

let c = FooCopy::default();
c.bar();
FooCopy::hello();
}

Course 6: Closures, Threads, Channels and Concurrency

Pierre Cochard, Tanguy Risset

Closures in Rust are anonymous functions that can be stored in variables, or passed to other processes as arguments. They can be found in a lot of places in the language, in order to allow functional-style programming, behavior customization or to provide concurrent/parallel code execution. They are defined by the following syntax |arguments| -> return_type { body }, for instance:

#![allow(unused)]
fn main() {
// Define a closure and store it into a variable:
let my_closure = |x: i32| -> i32 {
    println!("my_closure");
    x*2
};

// Execute the closure like you would normally do with a function:
let y = my_closure(2);
println!("{y}");
}

Borrowed captures

Just like in C++, closures can capture the environment it originates in and use external data in its own internal scope. By default, captured data, whether it is mutable or not, will be borrowed:

#![allow(unused)]
fn main() {
let x = 2;

let my_closure = || -> i32 {
    // Use a borrowed (immutable) capture of 'x', 
    // and return two times its value:
    x*2
};

println!("{}", my_closure());
}

#![allow(unused)]
fn main() {
// Same, but this time, we modify 'x' directly in the closure:
let mut x = 2;

// The closure itself also has to be made 'mutable' 
// in the case of a mutable borrow:
let mut my_closure_mut = || x *= 2;

my_closure_mut();
println!("{x}");
}

Moved captures

Instead of being borrowed, data can also be captured by value into a closure scope, using the move keyword before declaration:

#![allow(unused)]
fn main() {
let mut x = 2;

// Capturing 'x' by value. Here, it is made with a simple copy:
let mut my_closure_mut = move || {
    x *= 2;
    println!("x (closure): {x}");
};

my_closure_mut();
println!("x: {x}");
}

#![allow(unused)]
fn main() {
let mut x = vec![31, 47, 27, 16];

let mut my_closure_mut = move || {
    x.push(32);
    println!("{:?}", x);
};

my_closure_mut();
println!("{:?}", x);
}

One big specificity of closures is that they have a unique, anonymous type that cannot be written out. This can for instance be demonstrated by running the following piece of code:

#![allow(unused)]
fn main() {
// Utility function that prints out the type of a variable:
fn print_type_of<T>(_: &T) {
    println!("Type of my closure: {}", std::any::type_name::<T>());
}

let my_closure = |x: i32| -> i32 {
    x*2
};

print_type_of(&my_closure);
}

Therefore, passing a closure as an argument to a function using a specific type is not possible in Rust. Instead, in order to do that, one would have to use a trait. Indeed, all closures implement one or several of the following traits, depending on their nature and properties:

• FnOnce: applies to closures that can be called once. All closures implement this trait;
• Fn: applies to closures that don't move captured values out of their body and that don't mutate captured values, as well as closures that capture nothing from their environment. These closures can be called more than once without mutating their environment, which is important in cases such as calling a closure multiple times concurrently.
• FnMut: applies to closures that don't move captured values out of their body, but that might mutate the captured values. These closures can be called more than once.

A closure can then be passed as an argument the same way we do for passing trait-implementing objects, by using the Fn/FnOnce/FnMut(argument_type) -> return_type:

#![allow(unused)]
fn main() {
// All of the 'Fn' traits have the format:
// 'Fn(argument-types) -> return types'
fn exec_closure(x: i32, closure: impl Fn(i32) -> i32) -> i32 {
    closure(x)
}

let c = |x: i32| x + 27;
let r = exec_closure(31, c);

println!("{r}");
}

The generic form also works (and is usually preferrable):

#![allow(unused)]
fn main() {
fn exec_closure<T>(x: i32, closure: T) -> i32 
where 
    T: Fn(i32) -> i32 
{
    closure(x)
}
let c = |x: i32| x + 27;
let r = exec_closure(31, c);

println!("{r}");
}

let chirp_fn = |times: i32| {
    for _ in 0..times {
        println!("chirp!");
    }
}

// The struct to implement (use generics!):
struct Bird<...> { 
    chirp: ... 
}

// Create a new instance of 'Bird' with the chirp_fn closure:
let bird = Bird { chirp: chirp_fn };

// Call the 'chirp' closure from inside the struct:
// operator precedence priority can be found here: https://doc.rust-lang.org/reference/expressions.html
(bird.chirp)(10);

A std::thread object in Rust will execute a given closure in an independent (or parallel) context of execution. In the following example, the std::thread::spawn call will only return when it's done creating the thread, but not when the thread has actually finished executing:

#![allow(unused)]
fn main() {
// Spawn a new thread which will execute its given closure:
std::thread::spawn(|| {
    println!("Thread 1: chirp!");
});
// At the 'same time', print something from the main thread:
println!("Main thread: chirp chirp!");
}

In this case, the main function returns before the independent thread's println! call happens. This is why we can only see the "main thread" print output. Usually, a thread is bound to a local variable, and is waited upon before the parent context of execution finishes. This can be done by calling the .join() method on the thread handle:

#![allow(unused)]
fn main() {
// Bind the thread's "handle" to a variable:
let th = std::thread::spawn(|| {
    println!("Thread 1: chirp!");
});

println!("Main thread: chirp chirp!");

// Wait for 'th' to finish executing, and re-synchronise both threads:
th.join().unwrap();
}

use std::thread;
let mut var = 32;

let t1 = thread::spawn(move || {
    var += 1;
    println!("Thread 1: reading value {}!", var);
});

let t2 = thread::spawn(move || {
    var += 2;
    println!("Thread 2: reading value {}!", var);
});

var += 3;
println!("Main thread: reading value {}", var);

// Re-synchronise both threads:
t1.join().unwrap();
t2.join().unwrap();

Mutual exclusion, or mutex is a mechanism which prevents accessing the same data from multiple threads running at the same time. It relies on a locking system in order to do so: a thread must first ask to acquire the mutex's lock before being able to access the underlying protected data. The lock is a data structure that keeps track of whichever thread has exclusive access to the data. If the mutex happens to be locked at the time a thread tries to access the data, it will stall until the lock is eventually released, and the data is free to acquire.

#![allow(unused)]
fn main() {
use std::sync::Mutex;
// Instantiate a new Mutex<i32> instance with the value '32':
let var: Mutex<i32> = Mutex::new(32);
{
    // Acquire the mutex's lock (and panic in case of failure):
    let mut v = var.lock().unwrap();
    // Modify the value safely:
    *v += 32;
}
// Print the result:
println!("var = {var:?}");
}

#![allow(unused)]
fn main() {
use std::thread;

let mut var = 32;

let t1 = thread::spawn(move || {
    var += 1;
});

let t2 = thread::spawn(move || {
    var += 2;
});
// Re-synchronise both threads:
t1.join().unwrap();
t2.join().unwrap();

println!("Result: {var}");
}

As we could see in our previous example, a Mutex in itself is not sufficient to implement viable thread-safe data sharing:

• First is the issue of ownership, which could be solved using, for instance, a shared pointer.
• Second would be the issue of concurrency in accessing this shared pointer from multiple threads simultaneously.

In the Rust programming language, Atomic Reference Counting Arc<T>, which can be seen as an atomic shared pointer, is designed to remedy this very specific problem. It firstly solves the ownership issue by being "reference-counted", just like a standard Rc object, but also solves the concurrency issue by being atomic, meaning that is guaranteed to execute as a single unified transaction. When an atomic operation is executed on an object by a specific thread, no other threads can read or modify the object while the atomic operation is in progress. In other words, other threads will only see the object before or after the operation, there would be no intermediary state.

Our previous example can then be replaced by the following:

#![allow(unused)]
fn main() {
use std::thread;
use std::sync::{Arc, Mutex};

// We wrap the Mutex in a Atomically Reference-Counted object:
let arc = Arc::new(Mutex::new(32));

// We prepare two clones, for moving into the two distinct closures:
let rc1 = Arc::clone(&arc);
let rc2 = Arc::clone(&arc);

let t1 = thread::spawn(move || {
    let mut v = rc1.lock().unwrap();
    *v += 1;
});

let t2 = thread::spawn(move || {
    let mut v = rc2.lock().unwrap();
    *v += 2;
});

// Re-synchronise both threads:
t1.join().unwrap();
t2.join().unwrap();

println!("Result: {arc:?}");
}

Another way of making data thread-safe is by directly using atomic data structures. The Rust standard library provides a few of them in its std::sync::atomic module. The main difference with using Mutexes is that atomics are what we call lock-free: unlike Mutexes, its underlying mechanism never sleeps, but it spins (it will check data availability in a continuous loop), that's why we usually call them spinlocks. In real-time contexts, where thread sleep is not an option, it is always preferrable to use lock-free data structures.

Our previous example would for instance look like this with atomics:

#![allow(unused)]
fn main() {
use std::thread;
use std::sync::Arc;
use std::sync::atomic::AtomicI32;
use std::sync::atomic::Ordering;

// We replace 'Mutex::new()' with the following:
let arc = Arc::new(AtomicI32::new(32));
let rc1 = Arc::clone(&arc);
let rc2 = Arc::clone(&arc);

let t1 = thread::spawn(move || {
    // Acquire underlying data as a copy:
    let mut v = rc1.load(Ordering::Acquire);
    // Modify the copy:
    v += 1;
    // Update the value atomically, release the lock:
    rc1.store(v, Ordering::Release);
});

let t2 = thread::spawn(move || {
    // Another (more compact) way of doing this:
    rc2.fetch_add(2, Ordering::AcqRel);
});
// Re-synchronise both threads:
t1.join().unwrap();
t2.join().unwrap();

println!("Result: {arc:?}");
}

Another approach to multiple ownership and thread-safety in Rust would be using an mpsc::channel or mpsc::sync_channel, which are asynchronous/synchronous FIFO queues that store all the updated states of a value in a shared infinite buffer.

An mpsc::channel() call will return a tuple containing a handle to a Sender object and a Receiver object, which are by convention respectively named tx and rx. These two objects are positioned at each end of a FIFO which tunnels data between the two:

#![allow(unused)]
fn main() {
// Create a 'data channel' between a Sender `tx`, and a Receiver `rx`:  
let (tx, rx) = std::sync::mpsc::channel::<i32>();

// Send the values `32` and then `16` through the channel:
tx.send(32).unwrap();
tx.send(16).unwrap();

// Poll the channel, read data if available:
println!("n = {}", rx.recv().unwrap());
println!("n = {}", rx.recv().unwrap());
}

Example of sending from a separate thread:

#![allow(unused)]
fn main() {
use std::thread;
use std::sync::mpsc;
let (tx, rx) = mpsc::channel();

// Do the same thing in a separate thread:
let th = thread::spawn(move || {
    tx.send(32).unwrap();
    tx.send(16).unwrap();
});

th.join();

// Poll the channel, read data if available:
println!("n = {}", rx.recv().unwrap());
println!("n = {}", rx.recv().unwrap());
}

Or from multiple threads simultaneously:

#![allow(unused)]
fn main() {
use std::thread;
use std::sync::mpsc;

let (tx, rx) = mpsc::channel();
let mut vec = Vec::new();

for n in 0..8 {
    // Clone the Sender `tx` for each thread:
    let tx = tx.clone();
    vec.push(thread::spawn(move || {
        tx.send(n).unwrap();
    }));
}
for t in vec {
    t.join().unwrap();
}
for _ in 0..8 {
    // Consume the FIFO value-by-value:
    let value = rx.recv().unwrap();
    println!("Received value: {}", value);
}
}

#![allow(unused)]
fn main() {
fn count_to(N: i32) {
    for n in 1..=N {
        println!("{n}");
        std::thread::sleep(std::time::Duration::from_secs(1));
    }
}
let t1 = std::thread::spawn(|| {
    count_to(10)
});
let t2 = std::thread::spawn(|| {
    count_to(20)
});
t1.join().unwrap();
t2.join().unwrap();
}

use tokio::{join, spawn, time::{sleep, Duration}};

async fn count_to(N: i32) {
    for n in 1..=N {
        println!("{n}");
        sleep(Duration::from_secs(1)).await;
    }
}

#[tokio::main]
async fn main() {
    // Run the following code expressions on a same task:
    join!(count_to(10), count_to(15));
}