Gray Soft / Tags / Rust

Experimenting With Ownership

2014-09-19T14:54:55Z

Let's use a trivial exercise to see what we can learn about ownership, moving, borrowing, and more in Rust. Here's the idea:

We'll allocate a list of numbers
We'll add one to each number in the list
We'll print the resulting list of numbers

This is a simple process requiring only a few lines of code:

fn main() {
    let mut numbers = vec![1u, 2, 3];
    for n in numbers.mut_iter() {
        *n += 1;
    }
    println!("{}", numbers);
}

The output is hopefully what we all expect to see:

$ ./one_function 
[2, 3, 4]

In this code there is just one variable: numbers. That variable owns a list of numbers on the heap and it's scope is limited to the main() function, which is just a way to say that the data exists for the length of that function call. Since all three steps happen in that one function call, ownership doesn't really affect us here.

To better examine what ownership really means, let's add one small twist to our exercise:

The increment of each number in the list must happen in a separate function

That doesn't feel like a very big change to me, but exploring this one idea has really helped me get my head around ownership in Rust. Let's talk about why.

My instinct for the simplest way to make this change to the code was to try this:

fn increment_all(mut numbers: Vec<uint>) {
    for n in numbers.mut_iter() {
        *n += 1;
    }
}

fn main() {
    let numbers = vec![1u, 2, 3];
    increment_all(numbers);
    println!("{}", numbers);
}

Unfortunately, this code doesn't compile:

$ rustc broken_move.rs 
broken_move.rs:10:20: 10:27 error: use of moved value: `numbers`
broken_move.rs:10     println!("{}", numbers);
                                     ^~~~~~~
note: in expansion of format_args!
<std macros>:2:23: 2:77 note: expansion site
<std macros>:1:1: 3:2 note: in expansion of println!
broken_move.rs:10:5: 10:29 note: expansion site
broken_move.rs:9:19: 9:26 note: `numbers` moved here because it has type
`collections::vec::Vec<uint>`, which is non-copyable
(perhaps you meant to use clone()?)
broken_move.rs:9     increment_all(numbers);
                                   ^~~~~~~
error: aborting due to previous error

The error message, like most in Rust, is pretty good here. It does assume you are familiar with some Rust concepts though. What it essentially says is that the ownership of our simple list of numbers was moved and then we tried to use what we no longer owned.

The move happens on the line in main() where the code calls increment_all(). When we passed the list as an argument to that function, the numbers variable in increment_all() took over ownership of that list. Just like before, that now means the data exists during that function call, because the variable is scoped to the function. Note that this isn't what causes the compile error. It's fine to move the list into the second function, but it sets the stage for what really went wrong here.

The error points to the very next line of main() when the code tried to print the resulting list. increment_all() has returned and we moved ownership of our list into a variable in that function. Since it's done, so is our list. Accessing it again, to print it out, is a no go.

Rust doesn't allow this because under its rules there can be only one owner of data at any given time.

When the data was moved into increment_all(), the variable inside that function became the new owner. That means the variable in main() lost ownership.

Hopefully that explains the problem, but how do we fix it? My first thought was, can ownership be moved back to main()? Sure it can:

fn increment_all(mut numbers: Vec<uint>) -> Vec<uint> {
    for n in numbers.mut_iter() {
        *n += 1;
    }
    numbers
}

fn main() {
    let mut numbers = vec![1u, 2, 3];
            numbers = increment_all(numbers);
    println!("{}", numbers);
}

This fixes the move problem. The code compiles and again produces the expected output.

The list of numbers is still moved into increment_all(). The difference here is that increment_all() returns the list at the end of the call and main() has been modified to replace the variable contents with that returned list. This moves ownership back into the variable in main() at the end of the increment_all() call, so the printing code is legal again.

Of course, this is a little silly. What if we had moved multiple arguments in? Returning all of them we needed back could be awkward at best. What we need is a way to not move the list when we call increment_all(). Rust has exactly that:

fn increment_all(numbers: &mut Vec<uint>) {
    for n in numbers.mut_iter() {
        *n += 1;
    }
}

fn main() {
    let mut numbers = vec![1u, 2, 3];
    increment_all(&mut numbers);
    println!("{}", numbers);
}

Rust has two ways that you can borrow a value. Putting a & in front of it is a read-only borrow, while a &mut is a mutable (read/write) borrow.

Here we've modified the call of the second function to pass in a borrowed reference to the list, instead of the list itself. That function was also modified to declare that it would receive this referenced type. Beyond that, the code inside increment_all() didn't really change.

This is due to a cool feature of Rust's dot operator (.): it will dereference when needed. This meant numbers.mut_iter() still worked without us needing to write something like (*numbers).mut_iter().

Now, all of these solutions use mutability to actually change the underlying numbers. I wondered if there was a way to do this without needing to edit the data. Of course, there are. Let's try using an iterator to produce the transformed list:

fn increment_all<'a, I: Iterator<&'a uint>>(numbers: I) -> Vec<uint> {
    numbers.map(|&n| n + 1).collect()
}

fn main() {
    let mut numbers = vec![1u, 2, 3];
            numbers = increment_all(numbers.iter());
    println!("{}", numbers);
}

The idea here is to avoid passing in the full list in favor of an iterator that can be used to walk the list. Combined with a call to map(), a new list of modified numbers is produced and returned as a result.

The first new element here is that I've switched to using generics to describe the incoming parameter. This allows the function to take anything that implements the trait Iterator. We're no longer restricted to just a vector.

The second new element here is the lifetime I had to introduce: 'a. The reason is that the function now takes references to some numbers and the period those numbers will live is known in the caller, main(). The explicit specifier of the lifetime here is Rust's way of indicating that those numbers must survive at least through the increment_all() function call, so they can be used in that call.

Technically, there's still one mut in the code above. If we really want to remove that, we can just store the result in a separate variable:

fn increment_all<'a, I: Iterator<&'a uint>>(numbers: I) -> Vec<uint> {
    numbers.map(|&n| n + 1).collect()
}

fn main() {
    let numbers     = vec![1u, 2, 3];
    let incremented = increment_all(numbers.iter());
    println!("{}", incremented);
}

We now have a truly immutable program, which may or may not be helpful in an actual application.

There is another step we might take here. I mentioned before how we have a generic input now that allows us to accept a wider range of arguments. That's nice, but we didn't use an equally flexible return value. We always generate a list of numbers. What if you wanted to tack on other iterators, further modifying the data, before you generated the final list? Can we just return the in-progress Iterator with the map() tacked on? Yes and no.

Rust doesn't currently allow for generic return values, so we can't just say we'll give you back an Iterator. However, we can lookup what map() actually returns and specify that:

fn increment_all<'a, 'r, I: Iterator<&'a uint>>(numbers: I)
    -> std::iter::Map<'r, &'a uint, uint, I> {
    numbers.map(|&n| n + 1)
}

fn main() {
    let numbers                = vec![1u, 2, 3];
    let incremented: Vec<uint> = increment_all(numbers.iter()).collect();
    println!("{}", incremented);
}

This is almost surely the most flexible implementation of increment_all(). It could be combined with other iterators when needed. That said, I feel like the type definitions had to get extra cryptic to allow this. I had to lookup the details of the Map object and add another lifetime for the returned value: 'r. Rust also needed me to explicitly type a variable that I didn't need to before. It feels like a bit of a tradeoff to me.

Most of the above is what I've managed to get out of the not-well-named Lifetimes Guide after many readings and some clarifying discussions in Rust's IRC channel. I know that new and improved documentation for these concepts is in the works.

Taking Rust to Task

2014-09-19T14:54:24Z

Now that I've reached the point where I can get some Rust code running without asking questions in IRC every five minutes, I really wanted to play with some tasks. Tasks are the way Rust handles multiprocessing code. Under the hood they can map one-to-one with operating system threads or you can use a many-to-one mapping that I'm not ready to go into yet.

Probably one of the most exciting aspect of tasks in Rust, in my opinion, is that unsafe use of shared memory is rejected outright as a compile error. That lead me to want to figure out how you communicate correctly. (Spoiler: the same was you do in Ruby: just pass messages.)

Ready to dive in, I grossly simplified a recent challenge from work and coded it up in Rust. You can get the idea with a glance at main():

use std::collections::HashMap;

// ...

fn string_vec(strs: &[&'static str]) -> Vec<String> {
    let mut v = Vec::new();
    for s in strs.iter() {
        v.push(s.to_string());
    }
    v
}

fn main() {
    let mut services = HashMap::new();
    services.insert("S1".to_string(), string_vec(["A", "B"]));
    services.insert("S2".to_string(), string_vec(["A", "C"]));
    services.insert("S3".to_string(), string_vec(["C", "D", "E", "F"]));
    services.insert("S4".to_string(), string_vec(["D", "B"]));
    services.insert("S5".to_string(), string_vec(["A", "Z"]));

    let work = Work(Search::new("A".to_string(), "B".to_string()));

    let mut task_manager = TaskManager::new(services);
    task_manager.run(work);
}

The HashMap sets up the story. Let's assume we have various travel services: S1, S2, etc. Each of those services can reach various stops. For example, S1 can reach A and B. Now the work variable tells you what we want to do, which is to search for ways to get from A to B.

The twist is handled by TaskManager. It's going to run each service in an isolated separate process (a task in Rust speak) that only knows about its own stops. This means finding non-direct paths must involve inter-process communication.

The string_vec() helper just builds a vector of String objects for me. I'm not using String for its mutability, but it's more of an attempt to clarify ownership without scattering lifetime specifications everywhere. (This may not been ideal. Please remember that I'm still a pretty green Rust programmer.)

If the code I write works, it will find two possible paths for our search and indeed it does:

$ ./pathfinder 
Path: A--S1-->B
Path: A--S2-->C--S3-->D--S4-->B

The rest of this blog post will examine just how it accomplishes this.

Let's begin with a pretty trivial data structure:

#[deriving(Clone)]
struct Path {
    from:    String,
    to:      String,
    service: String
}
impl Path {
    fn new(from: String, to: String, service: String) -> Path {
        Path{from: from, to: to, service: service}
    }

    fn to_string(&self) -> String {
        self.from
            .clone()
            .append("--")
            .append(self.service.as_slice())
            .append("-->")
            .append(self.to.as_slice())
    }
}

This just defines a Path as two endpoints and the service that connects them. You can see that the to_string() method gives us the simple ASCII arrow output from the solution.

Search builds on Path:

#[deriving(Clone)]
struct Search {
    from:  String,
    to:    String,
    paths: Vec<Path>
}
impl Search {
    fn new(from: String, to: String) -> Search {
        Search{from: from, to: to, paths: vec![]}
    }

    fn services(&self) -> Vec<String> {
        self.paths.iter().map(|path| path.service.clone()).collect()
    }

    fn stops(&self) -> Vec<String> {
        let mut all = vec![];
        all.push(self.from.clone());
        all.push(self.to.clone());
        for path in self.paths.iter() {
            all.push(path.from.clone());
            all.push(path.to.clone());
        }
        all
    }

    fn add_path(&self, path: Path) -> Search {
        Search{ from:  path.to.clone(),
                to:    self.to.clone(),
                paths: self.paths.clone().append([path]) }
    }
}

A Search holds the endpoints we're currently trying to traverse and any paths collected so far in an attempt to reach our goal. The add_path() method is used with partial matches. It returns a new Search for the remaining distance with the partial Path added to the list.

The other methods, services() and stops(), just return lists of what has been used so far in the accumulated paths. These are helpful in avoiding building circular paths.

Note that both data structures so far are cloneable. This is so that copies can be made to sent across channels to other tasks.

We need two more aggregate data structures to be the messages that we will shuttle between tasks:

#[deriving(Clone)]
enum Job {
    Work(Search),
    Finish
}

enum Event {
    Match(Vec<Path>),
    Partial(Vec<Search>),
    Done(String)
}

A Job can be either a wrapped Search we want to perform or the special Finish flag. The latter just tells a task to bust out of its infinite listening-for-searches loop and exit cleanly. This enum lists the messages we can send to the service tasks.

Messages from a service task (back to our not yet examined TaskManager) are called an Event. There are three possible types. Match means we have a full solution, using the included paths. Partial means that the task matched part of the path and is sending back a list of searches to try for locating the rest of it. Again Done is a special flag that pretty much means, "I've got nothing." This flag includes the name of the service for a reason that will become obvious after we view this next helper object:

struct SearchTracker {
    counts: HashMap<String, uint>
}
impl SearchTracker {
    fn new<'a, I: Iterator<&'a String>>(mut service_names: I) -> SearchTracker {
        let mut tracker = SearchTracker{counts: HashMap::new()};
        for name in service_names {
            tracker.counts.insert(name.clone(), 0);
        }
        tracker
    }

    fn add_search(&mut self) {
        for (_, count) in self.counts.mut_iter() {
            *count += 1;
        }
    }

    fn mark_done(&mut self, name: String) {
        let count = self.counts.get_mut(&name);
        *count -= 1;
    }

    fn is_done(&self) -> bool {
        self.counts.values().all(|n| *n == 0)
    }
}

The idea behind SearchTracker is that we want to know when we're done seeing results from the various tasks. We can do that by expecting exactly one response (an Event) from each task for each Search sent.

This object just makes a counter for each service name passed into the constructor. You can then add_search() to bump all counters (because each Search is sent to all service tasks) and mark_done() to reduce a named counter when you receive a response from that service. The is_done() method will return true when all the counts balance out.

We need one last helper before we get into the actual process:

struct MultiTaskSender<T> {
    senders: Vec<Sender<T>>
}
impl<T: Clone + Send> MultiTaskSender<T> {
    fn new() -> MultiTaskSender<T> {
        MultiTaskSender{senders: vec![]}
    }

    fn add_sender(&mut self, sender: Sender<T>) {
        self.senders.push(sender);
    }

    fn send(&self, t: T) {
        for sender in self.senders.iter() {
            sender.send(t.clone());
        }
    }
}

As I said, each Search will be sent to all tasks. This simple multicaster just allows you to add_sender() as each task is built and later send() to all those channels. The actual object sent is handled as a generic type that we just need to be able to Clone and Send.

We're finally ready for the main workhorse of this code:

struct TaskManager {
    services:       HashMap<String, Vec<String>>,
    tracker:        SearchTracker,
    multi_sender:   MultiTaskSender<Job>,
    event_sender:   Sender<Event>,
    event_receiver: Receiver<Event>
}
impl TaskManager {
    fn new(services: HashMap<String, Vec<String>>) -> TaskManager {
        let (sender, receiver) = channel();
        TaskManager{ services:       services.clone(),
                     tracker:        SearchTracker::new(services.keys()),
                     multi_sender:   MultiTaskSender::new(),
                     event_sender:   sender,
                     event_receiver: receiver }
    }

    fn run(&mut self, work: Job) {
        self.launch_services();
        self.send_job(work);
        self.wait_for_services();
        self.send_job(Finish);
    }

    // ...
}

This shows you what a TaskManager keeps track of, which is just the data for our challenge, the helper objects, and various channels (the pipes of communication between Rust tasks). You can see how this gets setup in new().

Once we have everything we need to track, run() actually does the Job. It will:

Launch a task for each service
Send the full search we want to perform
Wait for and respond to reported work from the tasks
Signal all tasks to shutdown when the work is done

Two pieces of this process are beating heart of the system. Here's the first of those:

impl TaskManager {
    // ...

    fn launch_services(&mut self) {
        for (name, stops) in self.services.clone().move_iter() {
            let task_event_sender                = self.event_sender.clone();
            let (search_sender, search_receiver) = channel();
            self.multi_sender.add_sender(search_sender.clone());
            spawn( proc() {
                loop {
                    let job = search_receiver.recv();
                    match job {
                        Work(search) => {
                            if stops.contains(&search.from) &&
                               stops.contains(&search.to) {
                                let path  = Path::new(
                                    search.from,
                                    search.to,
                                    name.clone()
                                );
                                let paths = search.paths.append([path]);
                                task_event_sender.send(Match(paths))
                            } else {
                                let mut tos      = stops.clone();
                                let     previous = search.stops();
                                tos.retain(|stop| !previous.contains(stop));
                                if !search.services().contains(&name) &&
                                   stops.contains(&search.from)       &&
                                   !tos.is_empty() {
                                    let searches = tos.iter().map( |to| {
                                        let path = Path::new(
                                            search.from.clone(),
                                            to.clone(),
                                            name.clone()
                                        );
                                        search.add_path(path)
                                    } ).collect();
                                    task_event_sender.send(Partial(searches));
                                } else {
                                    task_event_sender.send(Done(name.clone()));
                                }
                            }
                        }
                        Finish       => { break; }
                    }
                }
            } );
        }
    }

    // ...
}

You're pretty much looking at a service task here (the whole part inside the call to spawn()). Inside, they are just an endless loop calling recv() to get new Work wrapped Search objects from the channel. The first if branch inside the match of Work(search) handles the simple case of the service matching the Search exactly.

When the else branch is selected, because we don't have a direct match, some work is done to see if a partial match is possible. (This is a foolish algorithm, by the way. It does partial matches if it can directly match the from endpoint and not the to. This rules out some viable scenarios, but it helped to keep this already large example smaller.)

If a partial match is found, it's transformed into a list of new searches to try that may later find direct matches or more partial matches. When no direct or partial match is found, the Done flag is sent back so TaskManager knows to stop waiting on this task.

The Finish match clause just breaks out of the loop as described previously. Outside of spawn() is a simple loop that creates each task and some code that prepares the variables for the task to capture.

impl TaskManager {
    // ...

    fn wait_for_services(&mut self) {
        loop {
            match self.event_receiver.recv() {
                Match(paths)      => {
                    let name = paths.last().expect("No path").service.clone();
                    self.tracker.mark_done(name);

                    let path_string = paths.iter().skip(1).fold(
                        paths[0].to_string(),
                        |s, p| s.append(p.to_string().as_slice().slice_from(1))
                    );
                    println!("Path: {}", path_string);
                }
                Partial(searches) => {
                    let name = searches.last()
                                       .expect("No search")
                                       .paths
                                       .last()
                                       .expect("No path")
                                       .service
                                       .clone();
                    self.tracker.mark_done(name);

                    for search in searches.iter() {
                        self.send_job(Work(search.clone()));
                    }
                }
                Done(name)        => { self.tracker.mark_done(name) }
            }
            if self.tracker.is_done() { break; }
        }
    }

    // ...
}

This chunk of code is the other half of the puzzle. It's another infinite loop listening on the Event channel. A full Match is pretty printed and a Partial is sent back out to the services in a wave of new searches. Regardless of the Event type, we record the response for the sending service, though where we find the service name varies by case. This allows us to exit this loop and the program when our tracker says we're done.

There's only one final method on TaskManager and it's what actually sends the messages to the service tasks, tracking each new Search as it goes out:

impl TaskManager {
    // ...

    fn send_job(&mut self, job: Job) {
        match job {
            Work(_) => { self.tracker.add_search(); }
            Finish  => { /* do nothing */ }
        }
        self.multi_sender.send(job);
    }
}

You can find the full code on GitHub.

Which Types to Type

2014-09-19T14:53:58Z

I've mentioned before that I'm writing some Rust code, specifically an RPN calculator as a simple exercise. I'm going to dump the code here so we can discuss one aspect of it, but do remember that I'm very new to Rust and this code could surely be better:

use std::fmt;
use std::os;

struct Stack {
    numbers: Vec<f64>
}
impl Stack {
    fn new() -> Stack {
        Stack{numbers: vec![]}
    }

    fn is_empty(&self) -> bool {
        self.numbers.is_empty()
    }

    fn push(&mut self, number: f64) {
        self.numbers.push(number);
    }

    fn result(&self) -> f64 {
        *self.numbers.last().expect("Stack empty.")
    }

    fn add(&mut self)      { self._do_binary_operation(|l, r| l + r); }
    fn subtract(&mut self) { self._do_binary_operation(|l, r| l - r); }
    fn multiply(&mut self) { self._do_binary_operation(|l, r| l * r); }
    fn divide(&mut self)   { self._do_binary_operation(|l, r| l / r); }

    fn _do_binary_operation(&mut self, operation: |f64, f64| -> f64) {
        let r = self.numbers.pop().expect("Stack underflow.");
        let l = self.numbers.pop().expect("Stack underflow.");
        self.numbers.push(operation(l, r));
    }
}
impl fmt::Show for Stack {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        let mut s = String::new();
        let mut i = self.numbers.len();
        for number in self.numbers.iter() {
            i -= 1;
            s = s.add(&format!("{}: {}\n", i, number));
        }
        s.pop_char();
        write!(f, "{}", s)
    }
}

struct Tokenizer {
    tokens: Vec<String>,
    i:      uint
}
impl Tokenizer {
    fn new(expression: &str) -> Tokenizer {
        Tokenizer{
          tokens: expression.split(|c: char| c.is_whitespace())
                            .map(|s| s.to_string())
                            .collect(),
          i:      0
        }
    }

    fn has_next_token(&self) -> bool {
        self.i < self.tokens.len()
    }

    fn next_token(&mut self) -> &str {
        if !self.has_next_token() { fail!("Tokens exhausted.") }

        let token = self.tokens[self.i].as_slice();
        self.i   += 1;
        token
    }
}

struct RPNCalculator {
    stack:  Stack,
    tokens: Tokenizer
}
impl RPNCalculator {
    fn new(stack: Stack, tokens: Tokenizer) -> RPNCalculator {
        RPNCalculator{stack: stack, tokens: tokens}
    }

    fn calculate(&mut self) -> f64 {
        while self.tokens.has_next_token() {
            let token = self.tokens.next_token();
            if !self.stack.is_empty() {
                println!("{}", self.stack);
            }
            println!("T: {}\n", token);
            match token {
                "+" => { self.stack.add(); }
                "-" => { self.stack.subtract(); }
                "*" => { self.stack.multiply(); }
                "/" => { self.stack.divide(); }
                n   => { self.stack.push(from_str(n).expect("Not a number.")); }
            }
        }
        if !self.stack.is_empty() {
            println!("{}\n", self.stack);
        }
        self.stack.result()
    }
}

fn main() {
    let     expression = os::args();
    let     stack      = Stack::new();
    let     tokenizer  = Tokenizer::new(expression[1].as_slice());
    let mut calculator = RPNCalculator::new(stack, tokenizer);
    println!("{}", calculator.calculate());
}

Rust has type inference meaning that it can often guess which type a given variable will hold. I haven't used many languages with this feature, so I'm not sure just how good Rust's implementation is compared to others, but it sure seems dynamite to me so far.

Just counting bare let statements, I'm using at least 10 variables that have no explicit type specification. There are many more in closures and passed values. Consider this line:

n => { self.stack.push(from_str(n).expect("Not a number.")); }

The function from_str() returns something like Option<&N>, where N is a primitive numeric type. Then expect() reduces that to N (from Some(N)) and I guess Rust figured out N had to be a float because it's handed off to this method definition:

fn push(&mut self, number: f64) {

I may have exactly how it figured all of that out wrong, but the end result is still awesome to me.

So which types do you really need? I've played around a little and here's what seems to work for me: declare the types of parameters and return values in function definitions. The rest mostly seems to take care of itself.

There are exceptions of course. You don't seem to need types on the self used in a method definition. The documentation is written without those and I've just copied that style. Also, occasionally the compiler will insist your clarify the type of a closure variable or let assignment. I add those only when prodded though and that seems quite rare so far.

Guard Clauses, Rust Style

2014-09-19T14:53:25Z

When I'm programming in Ruby, I will often use guard clauses to prevent undesirable scenarios. For example, let's say I'm building a simple Stack:

class Stack
  def initialize
    @numbers = [ ]
  end

  def push(number)
    @numbers.push(number)
  end

  def peek
    fail "Stack underflow" if @numbers.empty?

    @numbers.last
  end
end

stack = Stack.new

ARGV.each do |number|
  stack.push(number.to_f)
end

p stack.peek

If I only want to work with numbers everywhere, I add a line like the call to fail() above. This prevents a nil from being returned from peek(), ruining my expectation that I will have numbers everywhere.

When I first started playing with Rust, I wanted to write code the same way:

use std::os;

struct Stack {
    numbers: Vec<f64>
}
impl Stack {
    fn new() -> Stack {
        Stack{numbers: vec![]}
    }

    fn push(&mut self, number: f64) {
        self.numbers.push(number);
    }

    fn peek(&self) -> f64 {
        if self.numbers.is_empty() { fail!("Stack underflow"); }

        self.numbers.last()
    }
}

fn main() {
    let mut stack = Stack::new();

    for number in os::args().tail().iter() {
        stack.push(from_str(number.as_slice()).expect("Not a number"));
    }

    println!("{}", stack.peek());
}

But this code doesn't compile:

$ rustc guards.rs
guards.rs:18:9: 18:28 error: mismatched types: expected `f64` but found `core::option::Option<&f64>` (expected f64 but found enum core::option::Option)
guards.rs:18         self.numbers.last()
                     ^~~~~~~~~~~~~~~~~~~
error: aborting due to previous error

The complaint from Rust here is that self.numbers.last() isn't actually going to return a float. Instead it's going to return an Option<&f64>. This is how Rust handles null values. Option is an enum that, in my case, will hold either Some(&f64) or None.

I've already convinced myself that I won't get that None I've been trying to avoid, because I used the guard clause. However, the compiler doesn't know what I know and it isn't yet convinced. To appease it, I need to enumerate the possible scenarios:

    fn peek(&self) -> f64 {
        if self.numbers.is_empty() { fail!("Stack underflow"); }

        match self.numbers.last() {
            Some(number) => { *number }
            None         => { 0.0  /* won't get here */ }

        }
    }

Here I use pattern matching to get at the number inside the Option and this does work:

$ ./guards 42
42
$ ./guards
task '<main>' failed at 'Stack underflow', guards.rs:22

Of course, my code is a little silly. I had to make up a dummy return value that I know will never be used but that the compiler requires for completeness.

The better thing to do here would be to realize that the Rust compiler is trying to show me how to do things the Rust way and adapt:

    fn peek(&self) -> f64 {
        match self.numbers.last() {
            Some(number) => { *number }
            None         => { fail!("Stack underflow") }

        }
    }

This is better Rust style for the same code, but it's still a little wordy. This pattern is very common in Rust so Option has an expect() method that will either return the Some(<T>) or fail!() with an error if there is None.

I actually already snuck this pattern into the code I showed you. Remember my main() function?

fn main() {
    let mut stack = Stack::new();

    for number in os::args().tail().iter() {
        stack.push(from_str(number.as_slice()).expect("Not a number"));
    }

    println!("{}", stack.peek());
}

It turns out that from_str() also returns an Option, because the string you pass may not be a valid number. When that's the case, you'll get a None. I sidestepped that issue here with a call to expect().

That means the complete and most Rust-like translation of the Ruby script we started with is:

use std::os;

struct Stack {
    numbers: Vec<f64>
}
impl Stack {
    fn new() -> Stack {
        Stack{numbers: vec![]}
    }

    fn push(&mut self, number: f64) {
        self.numbers.push(number);
    }

    fn peek(&self) -> f64 {
        *self.numbers.last().expect("Stack underflow")
    }
}

fn main() {
    let mut stack = Stack::new();

    for number in os::args().tail().iter() {
        stack.push(from_str(number.as_slice()).expect("Not a number"));
    }

    println!("{}", stack.peek());
}

With this code, both the compiler and I know I'm not dealing with non-numbers.

Asking Better Questions

2014-09-19T14:52:52Z

I've been playing with some Rust lately and learning a bunch of new concepts.

As part of my experimentation, I built an RPN calculator in the language, just as an exercise that would require a moderate amount of code to be worked out. Honestly, I don't fully understand everything that I had to do to get this code working yet. Maybe 20% of it came about as me following instructions from what seem to be very helpful compiler errors.

I wanted to start attacking these concepts that I didn't understand to increase my knowledge. Of course, I was impatient. I had some working code and I knew what I was missing, so I jumped into IRC, pointed at the code, and asked some not-at-all complete questions. All I got was crickets.

This isn't a failing of the Rust community. It's a lesson I have to relearn every now and then. You have to take the time to present a good enough question that answering it is easy enough and worth it. It's hard work to get your head around 100 lines of code and, even if you do, you'll still be missing plenty of context if the question isn't really well formed. Given that, most people just ignore the question. That's probably for the better too, because any answers provided likely would have missed the points I really needed help with.

What it did do was remind me that I needed to ask better questions. Today I took the time to build a small example that addressed one of my key confusions with Rust so far: Lifetimes (plus Ownership, Borrowing, and References it turns out). Here's the code I whipped up:

// I'm trying to make sure I have my head around "lifetimes"
// after a few readings of the guide:
// http://doc.rust-lang.org/guide-lifetimes.html.  The following is
// a simple example of what I think I now know that I'll try to explain
// in this comment.
//
// Because the letters are "borrowed references," (Do I have my terms right?)
// they could potentially be freed before the Lists struct that contains them.
// Since this possibility exists, Rust requires the explicit lifetime 'a which
// indicates that the lifetime of a created Lists instance is tied to whatever
// references were passed into the letters slot.

#[deriving(Show)]
struct Lists<'a> {
    numbers: Vec<int>,
    letters: Vec<&'a str>
}

fn main() {
    let lists = Lists{numbers: vec![1, 2, 3], letters: vec!["A", "B", "C"]};
    println!("{}", lists);
}

I made a Gist out of that and then went back to IRC to ask people how correct my current understanding was. The effort really paid off. I got some great clarifications:

JEG2
  Can anyone tell me if my understanding of the explicit lifetime
  in this example, as explained by my comment, feels correct?
  https://gist.github.com/JEG2/ae7746544cef14be1606
…
kimundi
  JEG2: That sounds right
…
steveklabnik
  JEG2: oh hey!!!!
  JEG2: good to see you here :)
  <3
Sharp
  JEG2: It's very close to being right (I *think*). Lists and letters
  must have the same lifetime, period. It's not that Lists acquires
  the lifetime of letters when it's created.
kimundi
  JEG2: Not that in this example you are using string literals,
  which have 'static lifetime and thus the references are always valid
JEG2
  steveklabnik: Hey steve. Thanks.
steveklabnik
  JEG2: the lifetime guide is _terrible_ btw, and as soon as my guide
  is wrapped up, which should be this week, it's next on the re-write train
…
kimundi
  Sharp: Eh, that doesn't sound right
…
JEG2
  steveklabnik: Good to know. Thanks.
…
Sharp
  kimundi: Well, actually I think Lists is bound to live at most
  as long as any one of its lifetime parameters. So yeah, you're right.
  I am clearly still confused about lifetimes :P
kimundi
  yeah, that sounds more correct :)
  No, wait
…
kimundi
  Eh, nevermind, its correct. List can not live longer as the 'a lifetime
  because else it would not be able to be created.
…
Dr-Emann
  JEG2: minor thing: everything has a lifetime, whether it
  contains references or not. Rust doesn't just create one
  when there's a possibility of premature frees. It only
  makes you be explicit with them in those cases though.
…
JEG2
  Sharp and Dr-Emann: Good clarifications on lifetimes. Thank you.
Sharp
  You're welcome, glad you could get something out of my confusion :)
…
steveklabnik
  JEG2: i left a comment on your gist too
Dr-Emann
  JEG2: of note is that even though the lifetime of the references
  is defined as the same as the lifetime of the containing struct,
  you can store any reference which lives _at least_ as long as the struct.
steveklabnik
  JEG2: make that two comments
…
JEG2
  Dr-Emann: Ah, I did not know that. So it's legal for my reference
  to outlive the struct?
…
Dr-Emann
  JEG2: they do, in your case, even. You pass literal strings,
  which are references into read only memory in the executable itself.
  They live for the entirety of the program.
…
JEG2
  Dr-Emann: Gotcha.
Dr-Emann
  JEG2: they have the special lifetime 'static. But you can also
  make a string on the stack and include references into it,
  as long as your struct doesn't outlive the String.
JEG2
  steveklabnik: Thanks for the comments. I'm getting a more complete picture.
…
steveklabnik
  JEG2: awesome. I -really really- want to make sure we explain this well,
  but we're not quite there yet.

As Steve Klabnik said, he also posted some very helpful comments on my Gist.

In other words, I got quite a bit of help. That help is also on public IRC logs and Gists, so it might even be of use to others.

It really pays to spend some time developing your question asking skills and then working on remembering to put those skills to use.