DEV Community: Francesco Cogno

Exploring Azure CosmosDB with Rust - Part 2

Francesco Cogno — Wed, 19 Aug 2020 13:01:21 +0000

What we left behind

In the previous post we've set up our development environment. We pulled the relevant crates and explained how to interact with the unofficial Azure SDK for Rust. In this post we will learn how to insert documents into Cosmos DB.

Cosmos DB hierarchy

In the previous post we called the list_databases function. This implied that we can have more than one database for each Cosmos DB account. It's not over though: the Cosmos DB hierarchy is quite complex.

Here is a super simplified view of Cosmos DB entities and their relationship:

It reads from top to bottom. For example: "A Cosmos DB account can have zero or more databases. Each database can have zero or more collections. Each collection can have zero or more document". And so on.

In other words, before even starting to insert a document, we need at least:

A Cosmos DB account
A database
A collection/container.

In this context Collection and Container are synonyms. They are inconsistently named in the official docs and in the Azure portal. Just remember that are the same thing. Here I will adhere to the official docs and call them collections.

What is a document, anyway?

In the true spirit of a NoSQL, Cosmos DB lets you store almost any JSON you want as document. I said almost because your document must:

Include a unique field called id.
Have a partition key (this is custom and decided upon collection creation).
Must be at most 2 MB (as expressed in UTF-8).

There are other limits (you can check them here) but unless you do something weird (like creating an id of 1MB 💩) you are unlikely to hit them.

The 2 MB limitation, in practice, is not that bad. You can use the attachments feature of a document if you need to store blobs of data anyway.

Go ahead and create the Customers collection. We will use age as partition key. While you can use the SDK for this task, for the first tests I suggest you to use the Azure portal.

Be warned: Azure Portal is continuously changing for the better. The above screenshot can be outdated while you read this!

Down to the code

Now that we have the collection we need to specify it in our code. If you remember from the Cosmos DB hierarchy, a collection needs a database and a Cosmos DB account.

So the code is pretty straightforward:

let cosmos_client = ClientBuilder::new(&account, authorization_token)?;

// create a database client for our shiny database
let database_client = cosmos_client.into_database_client("shiny");
// create a collection client for our customers database
let collection_client = database_client.into_collection_client("customers");

Now we can call its functions! Let's start easy:

use azure_sdk_cosmos::responses::ListDocumentsResponse;

let response: ListDocumentsResponse<serde_json::Value> = 
    collection_client.list_documents().execute().await?;

println!("{:#?}", response);

Of course there are no documents yet but our first call succeeded (you will need to import serde_json in your Cargo.toml file for this to work).

Notice that Cosmos DB returned us a plethora of info. Most of this stuff we can safely ignore. The only important bit is the session token. In the previous post we talked about session consistency. This is how we achieve that in Cosmos DB.

Turbofish

The above call was cumbersome. We specified the return type by hand. It's something we do not usually do in Rust; generally the compiler is smart enough to figure out the correct type by itself.

In this case, though, we need to help it: the list_documents function can return any serializable type so the compiler does not know which one we want. In the example we asked for the plain JSON document list (notice the serde_json::Value type).

We can avoid specifying the return type (the ListDocumentsResponse part) if we use the turbofish syntax:

let response = collection_client
    .list_documents()
    .execute::<serde_json::Value>() // we passed the type here!
    .await?;

I generally prefer the turbofish syntax - if only because of its cool name - but some people find it hard to grasp so you can choose whichever you like. Makes no difference whatsoever!

Insert a document already!

Yes, you are right, we are not doing our job! Let's start by defining a customer to add. We will once more ask for serde_json help:

let customer = serde_json::from_str::<serde_json::Value>(
    r#"
    {
        "id": "e543ae93-27e2-45d6-b26d-eb83eb1a7762",
        "name": "Plo Koon",
        "homeworld": "Korin",
        "age": 43,
        "phones": [
            "+4123454 1234567",
            "+4123454 2345678"
        ]
    }"#,
)?;
println!("{:#?}", customer);

As you can see we are hardcoding the JSON. This is not necessary of course, we will see how to use Rust structs in a future blog post.

Now that we have the customer, let's call the create_document function! We need to pass the partition key and of course the document itself:

let response = collection_client
    .create_document()
    .with_partition_keys(PartitionKeys::new().push(43)?)    // let's pass the partition key
    .execute_with_document(&customer)                       // pass the document itself!
    .await?;
println!("{:?}", response);

Couple of things to note:

The SDK supports multiple PartitionKeys, as per API specification. This is not yet supported in Cosmos DB so for the time being stick with one key only.
Instead of the classic execute we have execute_with_document. This is due to a nasty Rust bug: as soon as it's fixed the SDK will revert to the standard function name.

By the way, you can create the PartitionKeys struct with the into() function, like this:

// cut
    .with_partition_keys(&(43i64.into()))
// cut

Let's run this code:

The addition went successfully. We also got back some info of our collection. For the curious, charge is the operation cost in terms of Cosmos DB units. The various LSN indicate the last sequence number of our database and is very important for data consistency. The quotas indicate how close to the limits we are.

Closing words

Now let's check in the portal if our late general has been added to our collection:

Notice how helpfully the data explorer shows you the id and our partition key.

You can also call the list_documents function again. This time it will not be empty!

In the next post we will use serde to work directly with the structs instead of using the JSON.

Happy coding,
Francesco Cogno

Exploring Azure CosmosDB with Rust - Part 1

Francesco Cogno — Wed, 05 Aug 2020 09:34:43 +0000

Stunning shot of the Bernina Range courtesy of Pietro Branca.

Azure CosmosDB and Rust

In this series of blob post we will explore the power of Azure CosmosDB, using Rust as programming language. This is not meant to be an authoritative essay on either: we will focus on GettingTheJobDone©.

In order to have a valid example, we will suppose to be tasked of creating a globally distributed shopping platform. We will start by identifying the functionality we need, how CosmosDB will help us to achieve our goals and, finally, how to interact with CosmosDB using Rust.
For the sake of this blog we will simplify a lot of stuff here - we won't be touching the front-end for example - but in the end you'll hopefully be able to complete the missing pieces on your own.

What we need

Our application will be composed of:

Goods database. Goods name, description, image and so on.
Inventory service: how many goods we have in storage.
Shopping basket service: every user can add items in the basket before committing to a purchase.

This is pretty standard stuff. Let's explore which out-of-the-box CosmosDB feature can help us.

Geo-replication

Azure CosmosDB can optionally replicate the data in various locations around the world. Turning this on is just a matter of clicking on a setting in the Azure Portal.
This is a great feature to have: if our shop supports customers from around the world we need to have a backend close to them otherwise the latency will kill the user experience. We do not want our Europe based customers to wait 600 ms on the network latency alone just because we happen to have chosen an US-based Azure region. With Azure CosmosDB we can enable and disable this setting at will. We can choose to have a primary read/write region and read-only secondary ones (single master setup) or elect to have many read/write regions at the same time (multi master setup).
For the goods database we will use a single master setup.
For the good and inventory service we will have a multi master replicated account (we assume to have one, big warehouse). The same applies to the shopping basket service. While unusual, this way our customers can start shopping in LA and commit the shopping basket in Rome!

Since we are unused to free launches in our trade, some of you might be wondering what would be the downside of having a replicated database. Generally speaking we know that a distributed database has either eventual consistency or horrible latency (CAP theorem being what it is).
In CosmosDB, however, we can use eventual consistency when it suits us and elect to have strong consistency only when needed.

The consistency levels of CosmosDB are quite complex because they support multiple scenarios: I will try to explain the more common ones here.

Consistency Levels

For our application we will use just three consistency levels: eventual, session, and strong. For a more precise and comprehensive list of the available consistency levels please consult the official documentation: https://docs.microsoft.com/en-us/azure/cosmos-db/consistency-levels.

Eventual consistency is basically the "give me the answer as fast as you can". This means we will get stale data or even some data updated while the remaining is not. For our goods service we will use eventual consistency: the updates are rare and we do not care if the customers sees a slightly outdated version of our goods. We care about having a fast UI.

Session consistency means "make sure that I see what I've just written". This means we can have outdated data but we are guaranteed to have our writes reflected in subsequent queries. The shopping basket service uses session consistency. We do not care if the other baskets are updated, we just care about our own: when the customer adds an item to the basket they expect it to happen!

Strong consistency means "make sure I get the most accurate data available". This means we will always get the updated data regardless of where the last write happened. The inventory service uses strong consistency. We want to make sure to have the items available before accepting a purchase!

So, why do we not use strong consistency everywhere? The answer is that strong consistency is slow. This is especially true if you have a georeplicated topology.

Time to live

In Azure CosmosDB you can optionally set an expiration date for every document. This means that CosmosDB will delete any expired document automagically. If you know that some of your data is useless after some time setting an expiration date avoids you to have a purge procedure in place. You can also ask CosmosDB to set expiration dates on his own without any intervention by your part!
Our shopping basket services stores expiring documents: if the customer does not update a shopping basket after a week we will let CosmosDB clean it up for us. This will keep our database free of useless data without a single line of code.

Embedded attachments

Azure CosmosDB treats attachments as first class parameter of your document. You can either store the attachments as links or you can ask CosmosDB to store them for you in a automatic blob storage. We can leverage this functionality in the goods database to store images. This is cool because we do not need to implement a "store and retrieval" image code, we can just add our images as attachments and CosmosDB will store them for us. It will also give us a valid Azure Storage URL for later retrieval. If the blob has public access (more info here), we can use the returned URL directly in our frontend with no additional code: Azure storage URIs are REST compliant!

Show me some code!

Enough jabber, let's see some code! We start off adding the mandatory reference to the unofficial SDK for Rust in Cargo.toml:

[dependencies]
azure_sdk_cosmos = "0.100.3"

This crate is fully async so it is a good idea to use the async derive offered by Tokio. This is accomplished by adding this dependency to Cargo.toml:

tokio = { version = "0.2", features = ["macros"] }

And by replacing the main function created by Cargo with this one:

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("Hello, world!");

    Ok(())
}

Now let's initialize the CosmosDB client. The CosmosDB client is our go-to trait that allows us to interact with our CosmosDB account. The client requires two things in order to successfully interact with CosmosDB: your account name and your authorization token (while there are other ways to authenticate the client, we will use the master key to keep things simple).

We retrieve these parameters from the command line, like this:

let account = std::env::args()
     .nth(1)
     .expect("pass the CosmosDB account name as first parameter!");
 let master_key = std::env::args()
     .nth(2)
     .expect("pass the CosmosDB master key as second parameter!");

And then we instantiate the client with these two lines:

// create an authorization token ginen a master key
let authorization_token = AuthorizationToken::new_master(&master_key)?;
// create a cosmos client for the account, using the authorization token above
let client = ClientBuilder::new(&account, authorization_token)?;

You can retrieve these info in the Keys tab of your CosmosDB blade in the Azure portal. For example:

The account name in my case is mindflavor2 (you can see it as the first part of the URI) and the two keys are shown as Primary Key and Secondary Key. Notice you can find the read only keys in the other tab. Please note that you can regenerate the keys at any time. This is useful if the keys are compromised because, say, you unfortunately posted a screenshot on the web, just like I did right now 😇.

Let's check what we can do with our shiny new client, shall we?
We can check the functions exported by this trait by looking at the docs azure_sdk_cosmos/trait.CosmosClient.html:

Let's try the list databases function. Clicking on the ListDatabaseBuilder gives us this:

Again, there are just two functions, execute and stream. This is a common theme to every SDK function: we call the function in the client trait and get back a Builder struct. We then call the execute function in the Builder struct to actually execute the call.

Don't panic, the Rust code is just one liner:

let databases = client.list_databases().execute().await?;

Seems too simple to be true? Go ahead and run it! The complete source code so far is:

use azure_sdk_cosmos::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let account = std::env::args()
        .nth(1)
        .expect("pass the cosmosdb account name as first parameter!");
    let master_key = std::env::args()
        .nth(2)
        .expect("pass the cosmosdb master key as second parameter!");

    let authorization_token = AuthorizationToken::new_master(&master_key)?;
    let client = ClientBuilder::new(&account, authorization_token)?;

    let databases = client.list_databases().execute().await?;

    println!("{:#?}", databases);

    Ok(())
}

If the key is right you will get the list of your databases! Hurrah! This time I even masqueraded my primary key properly in the screenshot 👍.

But, wait, you do not have a database? Just create one with the Azure portal or use the Rust SDK - you might have guessed, the only other Cosmos client function is called create_database 😉.

Last thing before closing this section: we have used the execute() function to get the list of databases but we also had the stream() function as well. Why two functions? The thing is, you can potentially have a lot of databases. In that case the execute() function would be very slow, having to return a lot of data. For this reason Azure limits the number of items returned by a single REST call. Don't worry though, Azure gives you a continuation token you can use to call the same API again with in order to keep enumerating the remaining items.

In other words you should keep calling the same API over and over until you are out of items (signaled by the lack of continuation token):

This is where the stream() function comes in. You do not have to code the loop by yourself: the stream() function handles this logic for you. In the following posts we will see examples on how to do this.

Create a database - builder pattern

The Rust CosmosDB SDK is meant to be as rusty as possible. In other word if the code compiles it should work as expected. That means catching as many errors during compile time as possible.
For example let's try to create a new database with this simple line:

client
    .create_database()
    .execute()
    .await?;

If we try this, the code won't compile. The compiler will tell us that the method execute does not exists in azure_sdk_cosmos::CreateDatabaseBuilder<'_, azure_sdk_core::No>. The important part is the No. If we look at the definition in the docs azure_sdk_cosmos/struct.CreateDatabaseBuilder.html:

We can clearly see that the struct has a type called DatabaseNameSet: ToAssign. This type, as stated by the compiler is No.
In other words the compiler is saying: "Is DatabaseNameSet? No! How can I create a database without a name? Go back and check you code!".

Yes, we forgot to give the new database a name! 🤦

The SDK, instead of failing at runtime, prevents us to compile the code altogether. That's nice!

Let's fix this by passing the database name:

client
    .create_database()
    .with_database_name(&"shiny") // we must specify a name!!!
    .execute()
    .await?;

Now the compiler is happy and so will be CosmosDB. Sure enough there it is!

Be mindful that errors at runtime can still happen. The SDK prevents you from making the wrong calls according to the documentation (these calls would fail every single time).

Correct calls can still fail for various reasons including service outages, network errors, order 66 and so on. It's important to handle these transient errors appropriately.

Next in series

This concludes this first post. We have learned how easy is to instantiate a Cosmos client and how to call a basic function. In the next post we will dive in the other functions available.

Happy coding,
Francesco Cogno

Let's build a Prometheus exporter in Rust

Francesco Cogno — Fri, 14 Jun 2019 21:18:15 +0000

Intro

In this post we will build a very simple Prometheus exporter in Rust. Prometheus is a time-series database especially useful in storing and retrieving OS vital signs. It can be paired with Grafana in order to create beautiful dashboards, like this one below:

Prometheus is peculiar because instead of receiving the events to store it goes on and retrieves them itself. There is no magic though: Prometheus just calls a preconfigured URI and expects a very specific plain text output. This is very elegant because this architecture decouples the service being monitored and the monitor adding an exporter service in between. It's the exporter's job to convert the service-specific metrics in a format Prometheus can understand and store.

There are tons of pre-made exporters allowing you to monitor the server CPU, the DHCP, etc... with ease. But since this is dev post we won't stop at combining tools written by others. Instead, we will build an exporter of our own. This will be a very simple exporter but I wanted to show you how easy it is to do it so hopefully you can implement an exporter on your own.

The goal

We want to keep an eye on the size of a folder. Prometheus can store the folder size every 60 seconds and Grafana can plot the size over time beautifully. It also allows us to create alerts: we can, for example, be notified via Telegram if the folder grows beyond a threshold.
But how we create the website needed by Prometheus in order to store the folder size? Enter Rust and an helper crate: Prometheus exporter base. Also, as a bonus, being Rust we will be sure the memory/CPU footprint will be low.

Prometheus exporter base

This crate is open source and MIT licensed (so you can use it freely) and it's designed to help you create a Prometheus exporter. It will handle most of the boilerplate required by Prometheus (such as rejecting anything but GET verbs and only answering to the /metrics URL). It also provides methods to format the output properly. So first thing first we need to import it by adding the relevant entry to the [Dependencies] section of out Cargo.toml file. This post is written using the version 0.3.0 of the crate so if you end up using a newer version you might have to account for breaking changes (if any).

The documentation is very terse: https://docs.rs/prometheus_exporter_base/0.3.0/prometheus_exporter_base/ but don't fret: all we have to do is to call the render_prometheus method.

Its signature is this one:

What a mouthful! Basically we need to pass a closure that will be called at every GET request. The closure should return a String or and error.
Yes, Rust type system can get carried away. Let's break down the methods one by one.

Bind address



addr: &SocketAddr,

This is the address our exporter will be listening to. We can pass 0.0.0.0 with a port of our choosing. For example this code will do:



let addr = ([0, 0, 0, 0], 32221).into();

Options



options: O
where
    O: Debug + Clone + Send + Sync + 'static

The options can be anything and it will be passed back to our closure at every call. The O type must also be cloneable, debuggable (meaning it must be printable in debug mode) and also must be sendable between threads. It also has to last forever (the 'static lifetime). We do not need options so we create an empty type just for that. Notice how the derive trick makes it trivial:



#[derive(Debug, Clone)]
struct MyOptions {}

Closure



perform_request: P
where
    P: FnOnce(Request<Body>, &Arc<O>) -> Box<dyn Future<Item = String, Error = Error> + Send + 'static> + Send + Clone + 'static,

This is a bit more complicated. What it means we must pass a function that takes the http Request as parameter. The second paramerer is the aforementioned custom option struct O, wrapped in an Arc (Arc allows multiple references of the underlying struct to be owned at the same time). The function must returns a Future: it must either resolve into a String - in case of success - or a failure::Error - in case something goes south. The bunch of other traits are generally less important besides the 'static lifetime. The 'static lifetime here warrants a mention: what it does is to restrict anything captured by the closure to live forever. In practice this just means that we either do not capture anything (easier) or make sure to move ownership into the closure.

Our exporter

Armed with this knowledge we can start creating a stub. Let's put this code as the main function of our exporter:



fn main() {
    let addr = ([0, 0, 0, 0], 32221).into();
    println!("starting exporter on {}", addr);

    render_prometheus(&addr, MyOptions {}, |request, options| {
        Box::new({
            println!(
                "in our render_prometheus(request == {:?}, options == {:?})",
                request, options
            );

            ok("it's working!\n".to_owned())
        })
    });
}

It will compile and you will get a working webserver listening on port 32221 that:

Will only allow GET verbs.
Will only answer to the path /metrics as per Prometheus specification.
Will run our code once invoked. Right now, it will just print something in the exporter's console window and return a fixed string to the caller.

Let's try it! After issuing cargo run in our crate we should be able to issue - in another terminal - curl http://localhost:32221/metrics -v. Since it's a standard HTTP GET you can use a browser to check it just the same.

Not bad for just few lines of crappy code!

Folder size calculation

Our stub right now doesn't do anything useful. We want it to be able to calculate the size of a folder. Let's write a function for that:



fn calculate_file_size(path: &str) -> Result<u64, std::io::Error> {
    let mut total_size: u64 = 0;
    for entry in read_dir(path)? {
        let p = entry?.path();
        if p.is_file() {
            total_size += p.metadata()?.len();
        }
    }

    Ok(total_size)
}

This function does not calculate the subfolders size but for our purposes will do just fine. Let's call it from our code. Start by adding this line to our main function:



let future_log = done(calculate_file_size("/var/log")).from_err();

Note here the done(...) - from_err() dance that is common with future combinators. Now we replace the ok("it's working\n".to_owned()) line with the future execution we just created:



future_log.and_then(|total_size_log| {
    ok(format!("{}\n", total_size_log))
})

This is easy! Now if we run the exporter again we should receive the proper answer instead of a static string! Nice! Firefox screenshot below:

Just for reference, now our code is like this:



#[derive(Debug, Clone)]
struct MyOptions {}

fn calculate_file_size(path: &str) -> Result<u64, std::io::Error> {
    let mut total_size: u64 = 0;
    for entry in read_dir(path)? {
        let p = entry?.path();
        if p.is_file() {
            total_size += p.metadata()?.len();
        }
    }

    Ok(total_size)
}

fn main() {
    let addr = ([0, 0, 0, 0], 32221).into();
    println!("starting exporter on {}", addr);

    render_prometheus(&addr, MyOptions {}, |request, options| {
        Box::new({
            println!(
                "in our render_prometheus(request == {:?}, options == {:?})",
                request, options
            );

            let future_log = done(calculate_file_size("/var/log")).from_err();
            future_log.and_then(|total_size_log| {
                ok(format!("{}\n", total_size_log))
            })
        })
    });
}

Prometheus compliance

This is all well and good but it does not mean our output is Prometheus compliant. In order to do so we should follow a specific format. Luckily the above helper crate has some methods to help us in this endeavor too.
We just need to create an instance of PrometheusCounter. The new(...) constructor requires:

A counter name. This is up to you to get correctly and I refer you the official Prometheus documentation for it. I will just use folder_size for this post.
A counter type. Again, please refer to the Prometheus documentation for this. I will go with counter on this one.
A counter help text. This is entirely optional but might help other people to understand what your counter is meant to do.

Once created we call the render_header() method so the crate will output the required header for our counter. The code will be like this:



let pc = PrometheusCounter::new("folder_size", "counter", "Size of the folder");
let mut s = pc.render_header();

That settles the header. All we need to do now is to output the values. Each counter can optionally have one or more attributes. For example our folder size counter can have the path attribute: this way you could have more than one instance of the same counter in a single response, each indicating a different resource. Our crate allows you to specify the attributes as slice of tuples: attribute-value. For our example we can use a vector like this:



let mut attributes = Vec::new();
attributes.push(("path", "/var/log/"));

Now we can call the render_counter function passing the attributes and the value. Like this:



pc.render_counter(Some(&attributes), total_size_log);

All we need to do is to append the rendered counter to the header we just obtained and we are done. Since we already have s that is a mutable String we can append (push) the correctly formatted String there:



s.push_str(&pc.render_counter(Some(&attributes), total_size_log));

Result

The final code is like this:



use futures::future::{done, ok, Future};
use prometheus_exporter_base::{render_prometheus, PrometheusCounter};
use std::fs::read_dir;

#[derive(Debug, Clone)]
struct MyOptions {}

fn calculate_file_size(path: &str) -> Result<u64, std::io::Error> {
    let mut total_size: u64 = 0;
    for entry in read_dir(path)? {
    let p = entry?.path();
    if p.is_file() {
        total_size += p.metadata()?.len();
    }
    }

    Ok(total_size)
}

fn main() {
    let addr = ([0, 0, 0, 0], 32221).into();
    println!("starting exporter on {}", addr);

    render_prometheus(&addr, MyOptions {}, |request, options| {
    Box::new({
        println!(
        "in our render_prometheus(request == {:?}, options == {:?})",
        request, options
        );

        let future_log = done(calculate_file_size("/var/log")).from_err();
        future_log.and_then(|total_size_log| {
        let pc = PrometheusCounter::new("folder_size", "counter", "Size of the folder");
        let mut s = pc.render_header();

        let mut attributes = Vec::new();
        attributes.push(("path", "/var/log/"));
        s.push_str(&pc.render_counter(Some(&attributes), total_size_log));

        ok(s)
        })
    })
    });
}

And the result is like this one:

Conclusion

Once added to Prometheus we can create beautiful dashboards like this one:

PS: I have built a couple of exporters myself, so if you want to see a more real world examples please refer to my GitHub profile!

Happy Coding,
Francesco

Rust builder pattern with types

Francesco Cogno — Thu, 26 Jul 2018 13:34:11 +0000

Intro

Rust has a very rich type system. It also has move semantics. Using these two features together you can build your APIs using the builder pattern. Let's see an actual example on why you would want to use the builder pattern and how to implement is (well, I'm showing you a way to implement it, not necessarily the best one).

Example

Suppose we have a function that takes a lot of parameters: some of them are mandatory, other are optional. For example:

fn cook_pasta(
    pasta_type: String,
    pasta_name: Option<String>,
    pasta_length: u64,
    altitude: u64,
    water_type: Option<String>,
) {
    // your code here
}

This method has two optional parameters, and three mandatory ones. Using it is ugly:

cook_pasta("Penne".to_owned(), None, 100, 300, Some("Salty".to_owned()));

The problem here is we have to explicitly tell the method to ignore an optional field (pasta_name) and also explicitly specify the other optional field (water_type). Being an Option forces us to wrap the optional field with Some(). Also positional fields are hard to interpret. For example we have two u64 fields: without looking at the method signature is really hard to tell what's what. Is 100 referring to the pasta_length or to the altitude?
This hampers readability as we have to jump back and forth in our code just to figure out what is happening.

With the builder pattern we want to achieve something like this:

cook_pasta()
    .with_pasta_type("Penne".to_owned())
    .with_pasta_length(100)
    .with_altitude(300)
    .with_water_type("Salty".to_owned())
    .execute();

This syntax is really better: we know with a glance what is pasta_length (100) and what is altitude (300). Also we do not need to wrap the optional fields in Some() nor we need to use None for optional ones we do not want to pass to the function.
Readability is way better at the expense of a extra execute() method call. But how to achieve it?

Builder struct

The trick here is to have a builder object that we continually move around, adding fields in the process. The builder object will own all the method fields. Something like this:

#[derive(Debug, Clone, Default)]
struct CookPastaBuilder {
    pub pasta_type: String,
    pub pasta_name: Option<String>,
    pub pasta_length: u64,
    pub altitude: u64,
    pub water_type: Option<String>,
}

Now out cook_pasta() function (we'll call it cook_pasta2() to differentiate if from the previous version) just creates a default instance of that structure.

fn cook_pasta2() -> CookPastaBuilder {
    CookPastaBuilder::default()
}

Our cook_pasta code will then be run using the CookPastaBuilder defined above:

impl CookPastaBuilder {
    fn execute(&self) {
        // your code here
    }
}

As it is now you can use it like this:

let mut cpb = cook_pasta2();
cpb.water_type = Some("Penne".to_owned());
cpb.pasta_length = 100;
cpb.altitude = 300;
cpb.water_type = Some("Salty".to_owned());

cpb.execute();

Not quite what we want but better than the original method. This solution has two problems: firstly you have no way to enforce the mandatory fields. If you forget to set a mandatory field you will notice it at runtime (bad, bad, bad!). Secondly, the syntax is cumbersome. We'll address the second issue first.

Moving around

Instead of giving access to inner fields we can expose them with moving methods. For example:

impl CookPastaBuilder {
    fn with_pasta_type(self, pasta_type: String) -> CookPastaBuilder {
        CookPastaBuilder {
            pasta_type,
            pasta_name: self.pasta_name,
            pasta_length: self.pasta_length,
            altitude: self.altitude,
            water_type: self.water_type,
        }
    }

Notice three things:

We are consuming the self object. This means we can no longer call methods on it (self in the method definition).
We construct a new CookPastaBuilder copying all the fields from the previous one except the field we want to assign (in the example pasta_type).
We pass the newly generated CookPastaBuilder to the caller (it becomes the new owner). This way we can chain these calls as they were on the same object. In reality we are changing CookPastaBuilders at each call.

Also we can get rid of the Some() wraps putting it inside the setter function:

    fn with_water_type(self, water_type: String) -> CookPastaBuilder {
        CookPastaBuilder {
            pasta_type: self.pasta_type,
            pasta_name: self.pasta_name,
            pasta_length: self.pasta_length,
            altitude: self.altitude,
            water_type: Some(water_type),
        }

Now we can do this:

cook_pasta2()
        .with_pasta_type("Penne".to_owned())
        .with_pasta_length(100)
        .with_altitude(300)
        .with_water_type("Salty".to_owned())
        .execute();

Nice!
But we still have to address the mandatory field check. For example this compiles fine:

cook_pasta2().execute();

But it's not fine at all (for instance, cooking pasta without actually having the pasta in the first place will not go well).

Types all around

Suppose now we have two builders instead of one. CookPastaBuilderWithoutPastaType and CookPastaBuilderWithPastaType (yes, I know, they suck but please bear with me).

If we define the execute method on the WithPasta variant only we can make sure no one will be able to call it on the WithoutPasta variant. At compile time. Which is good.

So our logical flow will be:

Call of cook_pasta2() will generate a CookPastaBuilderWithoutPastaType.
Calling with_pasta_type(..) will consume the CookPastaBuilderWithoutPastaType and return a CookPastaBuilderWithPastaType.
Now calling execute() will work because CookPastaBuilderWitPastaType implements the method.

If we were to call execute() without calling with_pasta_type(..) first we would get a compiler error.

But, hey, we have just handled one mandatory field. We have three of them! Sure you can come up with something like CookPastaBuilderWithoutPastaTypeWithoutAltitudeWithoutPastaLength and all the permutations (in this case 12) like CookPastaBuilderWithPastaTypeWithoutAltitudeWithPastaLength and CookPastaBuilderWithoutPastaTypeWithoutAltitudeWithPastaLength... but there is a better way of doing so in less keystrokes.

Generics?

We can use generics to achieve a better compromise. We have three mandatory fields:

pasta_type
pasta_length
latitude

We can simulate the presence or absence of a value with a boolean type. Something like:

#[derive(Debug, Default)]
pub struct Yes;
#[derive(Debug, Default)]
pub struct No;

Our new class becomes:

struct CookPastaBuilder<PASTA_TYPE_SET, PASTA_LENGTH_SET, ALTITUDE_SET>

These generic types can either be No or Yes indicating the fact the specific field has been assigned. For example setting the pasta_type field:

    fn with_pasta_type(
        self,
        pasta_type: String,
    ) -> CookPastaBuilder<Yes, PASTA_LENGTH_SET, ALTITUDE_SET> {
        CookPastaBuilder {
            pasta_type,
            pasta_name: self.pasta_name,
            pasta_length: self.pasta_length,
            altitude: self.altitude,
            water_type: self.water_type,
        }
    }

This function will return a new CookPastaBuilder instance with the PASTA_NAME_SET set on Yes so we know the field has been set. Notice that we are returning PASTA_LENGHT_SET and ALTITUDE_SET in this case because we do not want to change the underlying type for those fields (they can either be set or not and we won't change that here).

Doing so for every mandatory field means we end up with a type like this:

CookPastaBuilder<Yes, Yes, Yes>

This gives us the compile-time guarantee that our caller has set all the mandatory fields. All we need to do is to constrain the execution of the execute() function to this specific type:

impl CookPastaBuilder<Yes, Yes, Yes> {
    fn execute(&self) {
        // your code here
    }
}

Result

From the client perspective our API is still the same, this invocation works:

cook_pasta2()
    .with_pasta_type("Penne".to_owned())
    .with_pasta_length(100)
    .with_altitude(300)
    .with_water_type("Salty".to_owned())
    .execute();

But this does not because we forgot to set the mandatory altitude parameter:

cook_pasta2()
    .with_pasta_type("Penne".to_owned())
    .with_pasta_length(100)
    .with_water_type("Salty".to_owned())
    .execute();

The error will be like this one:

The no method named execute found for type CookPastaBuilder<Yes, Yes, No> in the current scope is not very helpful but at least you catch the error before runtime. At least the generic type names will help you determine what is missing:

That is if you add the necessary WHEREs to the struct declaration:

#[derive(Debug, Clone, Default)]
pub struct CookPastaBuilder<PASTA_TYPE_SET, PASTA_LENGTH_SET, ALTITUDE_SET>
where
    PASTA_TYPE_SET: ToAssign,
    PASTA_LENGTH_SET: ToAssign,
    ALTITUDE_SET: ToAssign,
{
    pasta_type_set: PhantomData<PASTA_TYPE_SET>,
    pasta_length_set: PhantomData<PASTA_LENGTH_SET>,
    altitude_set: PhantomData<ALTITUDE_SET>,

    pasta_type: String,
    pasta_name: Option<String>,
    pasta_length: u64,
    altitude: u64,
    water_type: Option<String>,
}

Last bit: the Phantoms

This is what we wanted: a builder pattern with elegant syntax, compile time checks. But we are using a fake generic, that is a generic not actively used in our code. Rust complains about this so in order to make him happy we add three new fields, one for each generic, of the type PhantomData. Do not worry, it won't appear at runtime so there is no cost in adding it (besides the nuisance of having them at all).

The final code if this one. Let me know what you think about it!

use std::fmt::Debug;
use std::marker::PhantomData;

#[derive(Debug, Default)]
pub struct Yes;
#[derive(Debug, Default)]
pub struct No;

pub trait ToAssign: Debug {}
pub trait Assigned: ToAssign {}
pub trait NotAssigned: ToAssign {}

impl ToAssign for Yes {}
impl ToAssign for No {}

impl Assigned for Yes {}
impl NotAssigned for No {}

pub fn cook_pasta(
    pasta_type: String,
    pasta_name: Option<String>,
    pasta_length: u64,
    altitude: u64,
    water_type: Option<String>,
) {
    // your code here
    println!(
        "cooking pasta! -> {:?}, {:?}, {:?}, {:?}, {:?}",
        pasta_type, pasta_name, pasta_length, altitude, water_type
    );
}

#[derive(Debug, Clone, Default)]
pub struct CookPastaBuilder<PASTA_TYPE_SET, PASTA_LENGTH_SET, ALTITUDE_SET>
where
    PASTA_TYPE_SET: ToAssign,
    PASTA_LENGTH_SET: ToAssign,
    ALTITUDE_SET: ToAssign,
{
    pasta_type_set: PhantomData<PASTA_TYPE_SET>,
    pasta_length_set: PhantomData<PASTA_LENGTH_SET>,
    altitude_set: PhantomData<ALTITUDE_SET>,

    pasta_type: String,
    pasta_name: Option<String>,
    pasta_length: u64,
    altitude: u64,
    water_type: Option<String>,
}

impl<PASTA_TYPE_SET, PASTA_LENGTH_SET, ALTITUDE_SET>
    CookPastaBuilder<PASTA_TYPE_SET, PASTA_LENGTH_SET, ALTITUDE_SET>
where
    PASTA_TYPE_SET: ToAssign,
    PASTA_LENGTH_SET: ToAssign,
    ALTITUDE_SET: ToAssign,
{
    pub fn with_pasta_type(
        self,
        pasta_type: String,
    ) -> CookPastaBuilder<Yes, PASTA_LENGTH_SET, ALTITUDE_SET> {
        CookPastaBuilder {
            pasta_type_set: PhantomData {},
            pasta_length_set: PhantomData {},
            altitude_set: PhantomData {},
            pasta_type,
            pasta_name: self.pasta_name,
            pasta_length: self.pasta_length,
            altitude: self.altitude,
            water_type: self.water_type,
        }
    }

    pub fn with_pasta_name(
        self,
        pasta_name: String,
    ) -> CookPastaBuilder<PASTA_TYPE_SET, PASTA_LENGTH_SET, ALTITUDE_SET> {
        CookPastaBuilder {
            pasta_type_set: PhantomData {},
            pasta_length_set: PhantomData {},
            altitude_set: PhantomData {},
            pasta_type: self.pasta_type,
            pasta_name: Some(pasta_name),
            pasta_length: self.pasta_length,
            altitude: self.altitude,
            water_type: self.water_type,
        }
    }

    pub fn with_pasta_length(
        self,
        pasta_length: u64,
    ) -> CookPastaBuilder<PASTA_TYPE_SET, Yes, ALTITUDE_SET> {
        CookPastaBuilder {
            pasta_type_set: PhantomData {},
            pasta_length_set: PhantomData {},
            altitude_set: PhantomData {},
            pasta_type: self.pasta_type,
            pasta_name: self.pasta_name,
            pasta_length,
            altitude: self.altitude,
            water_type: self.water_type,
        }
    }

    pub fn with_altitude(
        self,
        altitude: u64,
    ) -> CookPastaBuilder<PASTA_TYPE_SET, PASTA_LENGTH_SET, Yes> {
        CookPastaBuilder {
            pasta_type_set: PhantomData {},
            pasta_length_set: PhantomData {},
            altitude_set: PhantomData {},
            pasta_type: self.pasta_type,
            pasta_name: self.pasta_name,
            pasta_length: self.pasta_length,
            altitude,
            water_type: self.water_type,
        }
    }

    pub fn with_water_type(
        self,
        water_type: String,
    ) -> CookPastaBuilder<PASTA_TYPE_SET, PASTA_LENGTH_SET, ALTITUDE_SET> {
        CookPastaBuilder {
            pasta_type_set: PhantomData {},
            pasta_length_set: PhantomData {},
            altitude_set: PhantomData {},
            pasta_type: self.pasta_type,
            pasta_name: self.pasta_name,
            pasta_length: self.pasta_length,
            altitude: self.altitude,
            water_type: Some(water_type),
        }
    }
}

impl CookPastaBuilder<Yes, Yes, Yes> {
    pub fn execute(&self) {
        // your code here
        println!("cooking pasta! -> {:?}", self);
    }
}

pub fn cook_pasta2() -> CookPastaBuilder<No, No, No> {
    CookPastaBuilder::default()
}

fn main() {
    cook_pasta("Penne".to_owned(), None, 100, 300, Some("Salty".to_owned()));

    cook_pasta2()
        .with_pasta_type("Penne".to_owned())
        .with_pasta_length(100)
        .with_water_type("Salty".to_owned())
        .with_altitude(300)
        .execute();
}

Happy Coding

Francesco Cogno

Let's build Zork using Rust!

Francesco Cogno — Wed, 17 Jan 2018 19:02:34 +0000

Games like Zork are basically big state machines. You advance in the game performing actions that lead your character from situation to situation. Eventually you either die horribly or win the game. The purpose of this post is to build a - simplified - textual game. We use it as a pretext to explore one way of treating state machines using Rust (yes, it's a clickbaity title)...

State machines in Rust

There are various ways to model a state machine in Rust. Today we build on top of a gorgeous idea by Florian Gilcher (you can see his original tweet here: https://twitter.com/Argorak/status/940221231709683713). Basically he suggests to model state passing around functions pointers. This works beautifully because you end up splitting your states in different functions instead of having a huge match statement.

Let's see some code first. We will comment it afterwards.

#[derive(Debug)]
struct Machine;

struct StateFn(fn(&mut Machine) -> StateFn);

impl Machine {
    fn start(&mut self) -> StateFn {
        println!("start");
        StateFn(Self::state)
    }

    fn state(&mut self) -> StateFn {
        println!("state");
        StateFn(Self::end)
    }

    fn end(&mut self) -> StateFn {
        println!("end");
        StateFn(Self::end)
    }
}

Here we have a struct called Machine which will hold some information that will be hard to model as a state machine (empty in our case). We also define another struct, StateFn, which holds the current state (expressed as a function). The convention, here, is that each state function will accept a mutable reference of Machine and will spit out the next state.

The syntax might be baffling at first so let's take a look at it. This line:

struct StateFn(fn(&mut Machine) -> StateFn);

Reads: create a struct called StateFn. This struct will have one implicit field. This field will accept only function pointers. The function pointed must have a single parameter - mutable reference of Machine - and will return a owned StateFn.

The state machine depicted above is this one:

To "run" it we can use this simple code:

fn main() {
    let mut m = Machine;
    let mut c = StateFn(Machine::start);
    println!("m == {:?}", m);

    c = c.0(&mut m);
    println!("m == {:?}", m);

    c = c.0(&mut m);
    println!("m == {:?}", m);

    c = c.0(&mut m);
    println!("m == {:?}", m);

    c = c.0(&mut m);
    println!("m == {:?}", m);
}

The c.0() syntax allows us to extract the first implicit field of StateFn and call it as a function. We pass the function our world state which is a Machine instance. Reassigning our StateFn binding simulates the evolution of the state machine. We can remove that .0 function call implementing Deref.

Deref

Florian Gilcher gives us an elegant solution to get rid of the c.0() dereference. Rust allows us to implement custom deref behavior using the Deref trait. Let's do this:

impl Deref for StateFn {
    type Target = fn(&mut Machine) -> StateFn;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

With this code we can simplify this call:

c = c.0(&mut m);

with this one:

c = c(&mut m);

So, to recap, we pass around functions that represent our state in the state machine. The functions will manipulate our world. With this information we can implement our Zork clone!

The game

The game will be very simple: there will be just three rooms. This is the state machine of our game:

Here we have two "game-related" variables:

Player owns the key or not
Player has opened the door or not

Also, to give interactivity, we store in our "world" the command input by the player. Each state can inspect the command issued and act accordingly. For example we have a magic fountain in a room. The player may issue: "drink from the fountain". If we are in the right room we can let the avatar drink from the fountain. The same command can be invalid in another room though. Lastly we store the player name.

We can model it just like this:

#[derive(Debug)]
struct Player {
    name: String,
    has_key: bool,
}

#[derive(Debug)]
struct Game {
    player: Player,
    last_command: String,
    door_locked: bool,
}

Notice we have both "game-related" variables and "technical" variables jumbled together. This might not be desiderable: we could rid of the "game-related" variable by replacing them via specialized states. For example, instead of having a single room state we can have room_door_locked and room_door_unlocked. Something like this:

The text processor

In order to build a text-based game you have to handle free form text. Given this is a sample of a Rust state machine I will cheat and just match predefined strings. For example the room with the key can be written like this:

fn key_room_with_key(&mut self) -> StateStruct<Game> {
    match &self.last_command as &str {
        "" => {
            println!("You are in a dark room.");
            StateStruct::input_required(Self::key_room_with_key)
        }
        "inspect" => {
            println!("You are in a dark room. You see a key on the floor.");
            StateStruct::input_required(Self::key_room_with_key)
        }
        "pick up the key" => {
            println!("You gingerly pick up the key and store it for later use.");
            self.player.has_key = true;
            StateStruct::input_required(Self::key_room_empty)
        }
        "go back" => {
            println!("You go back in the hallway.");
            StateStruct::no_input_required(Self::hallway)
        }
        _ => {
            println!("I don't know how to do that! What do you want to do?");
            StateStruct::input_required(Self::key_room_with_key)
        }
    }
}

As you can see we just match for specific input strings. Remember, the last received command will be in the last_command field. We than do three things:

Print something to give feedback to the user.
Change the world (optional) modifying our mutable reference.
Move to the new state. Here we use two helper functions, input_required and no_input_required to signal if we have to wait for player input before activating the new state.

Main

The main method is just a loop. We start the state machine in the start state and play the state machine until we reach the end state. The main loop is oblivious of what's happening in the state machine, the state transition happen as result of state execution.

fn main() {
    use std::io::Write;
    let mut game = Game::default();

    // start the state machine.
    let mut sf = StateStruct::no_input_required(Game::start);

    // process the start state and progress to the next state.
    sf = sf(&mut game);

    // we play the machine until its end.
    while !sf.completed {

    // if the state requires input we ask the player to supply it.
        if sf.requires_input {
            let mut buffer = String::new();
            print!("> ");
            ::std::io::stdout().flush().unwrap();
            ::std::io::stdin().read_line(&mut buffer).unwrap();
            game.last_command = buffer[0..buffer.len() - 1].to_owned();
        } else {
            game.last_command = "".to_owned();
        }

    // now we play the next state and advance the machine.
        sf = sf(&mut game);
    }
}

As you can see the main code is straightforward.

Wrapping up

Now all we have to do is to implement the states our game will handle. The following complete code will implement the diagram above. Can you complete the dungeon without dying? Also, can you devise a more challenging dungeon to play? Let me know!

use std::ops::Deref;

type StateFn<T> = fn(&mut T) -> StateStruct<T>;
struct StateStruct<T> {
    function: StateFn<T>,
    requires_input: bool,
    completed: bool,
}

impl<T> StateStruct<T> {
    fn new(function: StateFn<T>, requires_input: bool, completed: bool) -> StateStruct<T> {
        StateStruct {
            function: function,
            requires_input: requires_input,
            completed: completed,
        }
    }

    fn input_required(function: StateFn<T>) -> StateStruct<T> {
        StateStruct::new(function, true, false)
    }

    fn no_input_required(function: StateFn<T>) -> StateStruct<T> {
        StateStruct::new(function, false, false)
    }

    fn completed(function: StateFn<T>) -> StateStruct<T> {
        StateStruct::new(function, false, true)
    }
}

impl<T> Deref for StateStruct<T> {
    type Target = StateFn<T>;

    fn deref(&self) -> &Self::Target {
        &self.function
    }
}

#[derive(Debug)]
struct Player {
    name: String,
    has_key: bool,
}

#[derive(Debug)]
struct Game {
    player: Player,
    last_command: String,
    door_locked: bool,
}

impl ::std::default::Default for Game {
    fn default() -> Self {
        Game {
            player: Player {
                name: "".to_owned(),
                has_key: false,
            },
            door_locked: true,
            last_command: "".to_owned(),
        }
    }
}

impl Game {
    fn reset(&mut self) {
        self.player.has_key = false;
        self.door_locked = true;
    }

    fn start(&mut self) -> StateStruct<Game> {
        println!("You wake up in hallway. Your memory is fuzzy... What's your name?");
        StateStruct::input_required(Self::save_name)
    }

    fn end(&mut self) -> StateStruct<Game> {
        println!("You eneded the game! {} wins! Congrats!", self.player.name);
        StateStruct::completed(Self::end)
    }

    fn save_name(&mut self) -> StateStruct<Game> {
        ::std::mem::swap(&mut self.player.name, &mut self.last_command);
        println!("Yes, that's right! You are {}!", self.player.name);
        StateStruct::no_input_required(Self::hallway)
    }

    fn hallway(&mut self) -> StateStruct<Game> {
        match &self.last_command as &str {
            "" => {
                println!("You are in a hallway. You can inspect it, go left or right.");
                StateStruct::input_required(Self::hallway)
            }
            "inspect" => {
                println!(
                    "You are in a hallway. It's unremarkable. You can go either right or left."
                );
                StateStruct::input_required(Self::hallway)
            }
            "go left" => {
                println!("You run left until you reach a dead end.");
                if !self.player.has_key {
                    StateStruct::no_input_required(Self::key_room_with_key)
                } else {
                    StateStruct::no_input_required(Self::key_room_empty)
                }
            }
            "go right" => {
                println!("You run left until you reach a dead end.");
                if self.door_locked {
                    StateStruct::no_input_required(Self::door_room_locked)
                } else {
                    StateStruct::no_input_required(Self::door_room_unlocked)
                }
            }
            _ => {
                println!("I don't know how to do that! What do you want to do?");
                StateStruct::input_required(Self::hallway)
            }
        }
    }

    fn key_room_with_key(&mut self) -> StateStruct<Game> {
        match &self.last_command as &str {
            "" => {
                println!("You are in a dark room.");
                StateStruct::input_required(Self::key_room_with_key)
            }
            "inspect" => {
                println!("You are in a dark room. You see a key on the floor.");
                StateStruct::input_required(Self::key_room_with_key)
            }
            "pick up the key" => {
                println!("You gingerly pick up the key and store it for later use.");
                self.player.has_key = true;
                StateStruct::input_required(Self::key_room_empty)
            }
            "go back" => {
                println!("You go back in the hallway.");
                StateStruct::no_input_required(Self::hallway)
            }
            _ => {
                println!("I don't know how to do that! What do you want to do?");
                StateStruct::input_required(Self::key_room_with_key)
            }
        }
    }

    fn key_room_empty(&mut self) -> StateStruct<Game> {
        match &self.last_command as &str {
            "" => {
                println!("You are in a dark room.");
                StateStruct::input_required(Self::key_room_empty)
            }
            "inspect" => {
                println!("You look around but there is nothing worth mentioning.");
                StateStruct::input_required(Self::key_room_empty)
            }
            "pick up the key" => {
                println!("There is no key to pick up!");
                StateStruct::input_required(Self::key_room_empty)
            }
            "go back" => {
                println!("You go back in the hallway.");
                StateStruct::no_input_required(Self::hallway)
            }
            _ => {
                println!("I don't know how to do that! What do you want to do?");
                StateStruct::input_required(Self::key_room_empty)
            }
        }
    }

    fn door_room_locked(&mut self) -> StateStruct<Game> {
        match &self.last_command as &str {
            "" => {
                println!("You are in a dimly lit room.");
                StateStruct::input_required(Self::door_room_locked)
            }
            "inspect" => {
                println!(
                    "You are in a dimly lit room. You notice a sickly looking fountain and a door."
                );
                StateStruct::input_required(Self::door_room_locked)
            }
            "drink from the fountain" => {
                println!("You drink the water and drop dead immediately. Tough luck!");
                self.reset();
                StateStruct::no_input_required(Self::start)
            }
            "unlock the door" => {
                if self.player.has_key {
                    println!("You use your key to unlock the door.");
                    self.door_locked = false;
                    StateStruct::input_required(Self::door_room_unlocked)
                } else {
                    println!("You do not have a key to use!");
                    StateStruct::input_required(Self::door_room_locked)
                }
            }
            "open the door" => {
                println!("The door is locked! You must find a key first!");
                StateStruct::input_required(Self::door_room_locked)
            }
            "go back" => {
                println!("You go back in the hallway.");
                StateStruct::no_input_required(Self::hallway)
            }
            _ => {
                println!("I don't know how to do that! What do you want to do?");
                StateStruct::input_required(Self::door_room_locked)
            }
        }
    }

    fn door_room_unlocked(&mut self) -> StateStruct<Game> {
        match &self.last_command as &str {
            "" => {
                println!("You are in a dimly lit room.");
                StateStruct::input_required(Self::door_room_unlocked)
            }
            "inspect" => {
                println!(
                    "You are in a dimly lit room. You notice a sickly looking fountain and an already unlocked door."
                );
                StateStruct::input_required(Self::door_room_unlocked)
            }
            "drink from the fountain" => {
                println!("You drink the water and drop dead immediately. Tough luck!");
                self.reset();
                StateStruct::no_input_required(Self::start)
            }
            "unlock the door" => {
                println!("The door is already unlocked!");
                StateStruct::input_required(Self::door_room_unlocked)
            }
            "open the door" => {
                println!("You open the door and escape the dungeon!",);
                StateStruct::no_input_required(Self::end)
            }
            "go back" => {
                println!("You go back in the hallway.");
                StateStruct::no_input_required(Self::hallway)
            }
            _ => {
                println!("I don't know how to do that! What do you want to do?");
                StateStruct::input_required(Self::door_room_unlocked)
            }
        }
    }
}

fn main() {
    use std::io::Write;
    let mut game = Game::default();
    let mut sf = StateStruct::no_input_required(Game::start);

    sf = sf(&mut game);

    while !sf.completed {
        // println!("game == {:?}", game);
        if sf.requires_input {
            let mut buffer = String::new();
            print!("> ");
            ::std::io::stdout().flush().unwrap();
            ::std::io::stdin().read_line(&mut buffer).unwrap();
            game.last_command = buffer[0..buffer.len() - 1].to_owned();
        } else {
            game.last_command = "".to_owned();
        }
        sf = sf(&mut game);
    }
}

Happy Coding,
Francesco Cogno

Tips for the technical interview from a casual interviewer

Francesco Cogno — Wed, 13 Dec 2017 11:37:10 +0000

During my career I was asked to help in the recruitment process as technical expert. It's not my main task (I'm a dev after all) but what better way to judge a dev than to use another dev? I've done this more and less 50 times so far so I'd like to share my tips about it. I hope to help you prepare better for a technical interview and to be more confident in your abilities. Bear in mind that is my point of view: different people lead to different interviews even if corporations try to standardize them.
Also note that I'm referring to the interviewer as a "he" instead of "she" because I'm a man: for this reason it comes more naturally to me. It does not imply the interviewer must be a male. Gender is irrelevant here.

Rule 1: Do not bulls**t

When facing a technical interviewer ask first what kind of work he does. If he's someone who actively work on technology you must assume he knows the answer of the question he's asking. At the very least he has the answer written somewhere.
If you try random guesses you might get lucky and let him think you know the subject. But chances are of failing miserably, especially if the answer if more complex than a "yes or no". In that case you will lose all your credibility in a instant. Nobody wants to work with a guy who sells false information. Do you want to base your work on a random assumption? If it's wrong you may end up losing weeks of work. Personally if I smell you guessing, even if the guess is right, I will poke you with more details. And catch your lie sooner or later.
So if you do not know the answer state it clearly. From then you can start speculating, maybe even reasoning with the interviewer. It makes you sincere and allows you to express your reasoning skills.
On a personal side, I like people able to admit being wrong and not being omniscient. It makes them excellent working partners.

Rule 2: Explain your resume

Your CV can be "inflated" for HR purposes. I can understand that. But when asked by a professional if you really are a master of a technology do not lie. This is similar to the do not bullshit rule above. I will most likely figure out if you are not a master. For example, do not state you are a blockchain guru if you do not know what a Merkle tree is. I will ask you that and see through your lie. Just say something like "I know I've written guru but I meant from the end-user perspective, not a dev one". It puts things in context. I might still ask you if you know what consensus means. But I definitely will not ask you about Merkle trees.
This is true even for "basic" knowledge. Basic knowledge is even easier to verify. But more on that in the next section.

Rule 3: Know the basics

I have told you to clearly state if you do not know something. But you must know the basics. Applying to a technical position without knowing the basics of the trade is inexcusable.
For example, if you are applying for a DBA role you must know what and index is. I do not care if you know the syntax used to create one. I need you to know what indexes are and why they are useful. This is true regardless of the seniority of the role.
Other examples, taken from my experience:

If you pretend to be a C programmer you must know the distinction between stack and heap.
If you pretend to be a SQL Server dev you must know what INNER JOIN and LEFT JOIN are.
If you pretend to be a C# programmer you must know what a static method is.
If you pretend to be a Rust programmer you must know what mutability is.

You got the gist. The syntax, the details are useless. You can always look them up using your search engine. But if you do not know what you are talking about you do not even know what to find.
Bottom line: if you are clueless of a tech better to say so from the start. There is no shame in it. But do not expect to be hired for a senior C# developer position if you struggle explaining what inheritance is.

Rule 0: Be yourself

This is not technical but I think it's worth mentioning. Be yourself. Truly. The technical interviewer does not care if you are funny or smiling or whatever. He cares about what you know and what you can do. If you spend energy trying to appear different than you are you are wasting resources. Wasting resources is bad, even if it's your brain and not a memory bank.

You are a smartass? I don't care. You are introvert? I don't care. You are a minority? I don't care. You come from another planet and are allergic to kryptonite? I do not care. I am here to judge you from a technical standpoint only. If you say something very, very wrong (for example: "the best GC is the one used by C") no amount of smiles and posturing can change my mind.
On a personal note I have worked with many different people. Competence goes beyond everything. I prefer to work with someone skilled with gdb even if he's an asshole than a very cool, smart but useless guy. Of course I'm terrible at debugging so I might be biased on that :).

Rule 4: Ask questions

When working on a project you can ask questions. Maybe something is not clear. Maybe you think a different approach can be more productive. The point is, when working interaction is the key. So I expect you to ask questions during the interview. For example I might ask you to sketch a tree. You can ask "what for"? It gives you context. It's a reasonable question. Of course you can go on and sketch a binary tree. It's fine. But in reality nobody creates a binary tree for no reason.
If I answer your question with: "the tree is used to speed up lookup searches" you might reply: "why don't we use an hash set instead?"
This is just an example but it gives an incredible amount of information to the interviewer: you know what trees are, what hashsets are and when they are useful. That's a lot of information in few sentences. And in our trade information density is a plus!

Rule 5: Prepare samples of your work

Nothing speaks better to a dev than code. So please bring some code with you. Even if you are completely green nowadays people expect to see your GitHub profile. And no, blindly forking cool projects does not count. You have to have built something. It can be a simple math lib or a utility program.
It shows two things:

You have done something. We dev know that it's really difficult to create something working. The idea is not enough. You have to fight every line to get it working. You have to read the documentation. You have to build a test case. You have to debug. And every step will be hard. But you did even if the result are 20 lines of code. SLOC is meaningless in this context.
You know the basics (source control, ssh, etc...).

Please do not rant about an hypothetical project. I do not care if you are planning to create a cool Raspberry Pi project. I care if you have done it.
Also do not give me a boring university project: a program that implements merge sort is "meh". If you are out of ideas, automation is a good start. Do you find yourself sorting you photos manually every time? Build a script to do that. It's way more informative that the nth useless, academic project.

Final rule: Be proud

It has been mentioned somewhere in dev.to too (I can't find the post right now, sorry). Please, please, be proud of what you do. You can only code in BASIC? Be proud of it. You do not know how to CUDA? Don't be intimidated. In the mind of the technical interviewer being able to do something means you can learn. But if you say: "I know a little bit of BASIC, but not well and I haven't done anything with it" you are downplaying your skills and your love for software development. The latter, to a dev, a guy who spends its life in coding, is a showstopper.

What do you think? If you have questions don't hesitate to ask.

Happy coding,
Francesco Cogno

Rust futures: an uneducated, short and hopefully not boring tutorial - Part 5 - Streams

Francesco Cogno — Wed, 06 Dec 2017 11:38:45 +0000

Intro

In our last post we saw how to build a complete Future. While being a contrived example we saw what is expected from a future: do not block as much as possible and unpark the task only when necessary. In this post we will expand the future in order to return a stream of values.

Streams are akin to iterators: they produce multiple outputs of the same type over time. The only difference here is how we consume them. Instead of using Rust's for statement we will ask our reactor to do it for us. How?

ForEach combinator

Instead of iterating manually between a streams items we use a specific combinator called for_each. But... ForEach implements Future so we can pass it to a reactor or even chain, join etc... with other futures! It's really cool.

Let's build one, shall we?

impl Stream

The Stream trait is very similar to the Future trait:

pub trait Future {
    type Item;
    type Error;
    fn poll(&mut self) -> Poll<Self::Item, Self::Error>;

    // <-- CUT -->
}

pub trait Stream {
    type Item;
    type Error;
    fn poll(&mut self) -> Poll<Option<Self::Item>, Self::Error>;

    // <-- CUT -->
}

Both traits have many more functions; since those functions have defaults you do not need to implement them if you don't need to. Let's focus on the poll function:

    // Future
    fn poll(&mut self) -> Poll<Self::Item, Self::Error>;

    // Stream
    fn poll(&mut self) -> Poll<Option<Self::Item>, Self::Error>;

The Stream trait can optionally return an Item. The Future must do so. The convention here is: if your stream has more data to produce and is readily available return a Ok(Async::Ready(Some(t))). If the data to produce is not yet ready return a Ok(Async::NotReady). If you are done return Ok(Async::Ready(None)). In case of errors you can return Err(e) as usual. So, to summarize:

Situation	`Future`	`Stream`
Item to return ready	`Ok(Async::Ready(t))`	`Ok(Async::Ready(Some(t)))`
Item to return not ready	`Ok(Async::NotReady)`	`Ok(Async::NotReady)`
No more items to return	N.A.	`Ok(Async::Ready(None))`
Error	`Err(e)`	`Err(e)`

Simple stream

Let's build a very simple stream: one that returns the integers from 0 up to X. Let's see the code first:

struct MyStream {
    current: u32,
    max: u32,
}

impl MyStream {
    pub fn new(max: u32) -> MyStream {
        MyStream {
            current: 0,
            max: max,
        }
    }
}

impl Stream for MyStream {
    type Item = u32;
    type Error = Box<Error>;

    fn poll(&mut self) -> Poll<Option<Self::Item>, Self::Error> {
        match self.current {
            ref mut x if *x < self.max => {
                *x = *x + 1;
                Ok(Async::Ready(Some(*x)))
            }
            _ => Ok(Async::Ready(None)),
        }
    }
}

The important part here is the poll function. poll takes a mutable reference of self so we can mutate the inner fields. What we do it to check if we have returned the last number (max) and then either terminate the stream or return the actual number and increment it.

Note that while here we have an upper bound you are not forced to specify it. So we could return all the numbers from here to infinity (or overflow, whichever comes first :)).

Consume a stream

To consume a stream we can use the for_each combinator we saw earlier. Let's print those numbers:

let mut reactor = Core::new().unwrap();
let my_stream = MyStream::new(5);

let fut = my_stream.for_each(|num| {
    println!("num === {}", num);
    ok(())
});

I will not spoil the surprise by posting the results :). Anyway note that each closure is a future in itself. You can tell because we are calling the ok(()) lowercase function.
We can call other futures, chain them and so on as usual. In our example we are simply returning ok.

Spawn futures during the event loop

Sometimes when producing items in streams we might want to spawn other futures. There are various reasons to do so (mainly: do not block if you can help it!). Rust's futures allow you to add futures to an existing event loop using the execute function of a reactor. There is a gotcha, however: the spawned future must not return anything. The function signature is this one:

For example we use a slightly modified wait-in-another-thread future written in the previous posts. We revise our stream like this:

impl Stream for MyStream {
    type Item = u32;
    type Error = Box<Error>;

    fn poll(&mut self) -> Poll<Option<Self::Item>, Self::Error> {
        use futures::future::Executor;

        match self.current {
            ref mut x if *x < self.max => {
                *x = *x + 1;

                self.core_handle.execute(WaitInAnotherThread::new(
                    Duration::seconds(2),
                    format!("WAIT {:?}", x),
                ));
                Ok(Async::Ready(Some(*x)))
            }
            _ => Ok(Async::Ready(None)),
        }
    }
}

The important part here is the execute code. Here we are spawning another future in the event loop (a future that will just wait for two seconds and then print WAIT <number>). Remember, this is supposed to be a daemon-like future so it must not return anything (except maybe an error).

To test this we'll use this code:

fn main() {
    let mut reactor = Core::new().unwrap();

    // create a Stream returning 5 items
    // Each item will spawn an "inner" future
    // into the same reactor loop
    let my_stream = MyStream::new(5, reactor.handle());

    // we use for_each to consume
    // the stream
    let fut = my_stream.for_each(|num| {
        println!("num === {:?}", num);
        ok(())
    });

    // this is a manual future. it's the same as the
    // future spawned into our stream
    let wait = WaitInAnotherThread::new(Duration::seconds(3), "Manual3".to_owned());

    // we join the futures to let them run concurrently
    let future_joined = fut.map_err(|err| {}).join(wait);

    // let's run the future
    let ret = reactor.run(future_joined).unwrap();
    println!("ret == {:?}", ret);
}

Here we also show how to join a stream with a future. The map_err dance is needed, as before, to make errors compatible (see Rust futures: an uneducated, short and hopefully not boring tutorial - Part 2).

If we run this code you can expect an output like this:

num === 1
num === 2
num === 3
num === 4
num === 5
"Manual3" starting the secondary thread!
"Manual3" not ready yet! parking the task.
"WAIT 1" starting the secondary thread!
"WAIT 1" not ready yet! parking the task.
"WAIT 2" starting the secondary thread!
"WAIT 2" not ready yet! parking the task.
"WAIT 3" starting the secondary thread!
"WAIT 3" not ready yet! parking the task.
"WAIT 4" starting the secondary thread!
"WAIT 4" not ready yet! parking the task.
"WAIT 5" starting the secondary thread!
"WAIT 5" not ready yet! parking the task.
"WAIT 1" the time has come == 2017-12-06T10:23:30.853796527Z!
"WAIT 1" ready! the task will complete.
"WAIT 2" the time has come == 2017-12-06T10:23:30.853831227Z!
"WAIT 2" ready! the task will complete.
"WAIT 3" the time has come == 2017-12-06T10:23:30.853842927Z!
"WAIT 3" ready! the task will complete.
"WAIT 5" the time has come == 2017-12-06T10:23:30.853856927Z!
"WAIT 5" ready! the task will complete.
"WAIT 4" the time has come == 2017-12-06T10:23:30.853850427Z!
"WAIT 4" ready! the task will complete.
"Manual3" the time has come == 2017-12-06T10:23:31.853775627Z!
"Manual3" ready! the task will complete.
ret == ((), ())

Notice even if we spawned the task 5 after the task 4 the completion order is scrambled. Also, your output would likely be different.

But what if we did not join the "Wait for 3 seconds" future?

The revised code is like this:

fn main() {
    let mut reactor = Core::new().unwrap();

    // create a Stream returning 5 items
    // Each item will spawn an "inner" future
    // into the same reactor loop
    let my_stream = MyStream::new(5, reactor.handle());

    // we use for_each to consume
    // the stream
    let fut = my_stream.for_each(|num| {
        println!("num === {:?}", num);
        ok(())
    });

    // let's run the future
    let ret = reactor.run(fut).unwrap();
    println!("ret == {:?}", ret);
}

We will notice that the code will return almost immediately with this output:

num === 1
num === 2
num === 3
num === 4
num === 5
ret == ()

The background futures did not get a chance to run.

Next steps

In the following posts we will, at least, cover the await! macro to streamline our futures.

Happy Coding

Francesco Cogno

Rust futures: an uneducated, short and hopefully not boring tutorial - Part 4 - A "real" future from scratch

Francesco Cogno — Tue, 21 Nov 2017 13:43:56 +0000

Intro

In the previous posts we covered the basics of how to handle Futures. We are now able to chain them, execute them and even create them. But, so far, our futures are not really delegating the execution to another thing. In Part 3 we cheated parking and immediately unparking the future. This trick allowed our future to progress but it was a poor example of real life future. Let's correct this with another, more fitting, example.

A timer future

The simplest future we can create is the timer (as we did in part 3). But this time, instead of unparking the future's task immediately we want to leave the task parked until it's ready to complete. How can we achieve this? The easiest way it to detach a thread. This thread will lay waiting for some time and then it will unpark our parked task.

This is a good simulation of what happens with asynchronous IO. We are notified when some data is available by another entity (generally the OS). Our thread - remember, for simplicity sake think about the reactor as single threaded - can perform other tasks while waiting to be notified.

Timer revised

Our stuct will be very simple. It will contain the expiration date and whether the fact the task is running or not:

pub struct WaitInAnotherThread {
    end_time: DateTime<Utc>,
    running: bool,
}

impl WaitInAnotherThread {
    pub fn new(how_long: Duration) -> WaitInAnotherThread {
        WaitInAnotherThread {
            end_time: Utc::now() + how_long,
            running: false,
        }
    }
}

The DateTime type and the Duration one are from the chronos crate.

Spin wait

To wait for the time we can use this code:

pub fn wait_spin(&self) {
    while Utc::now() < self.end_time {}
    println!("the time has come == {:?}!", self.end_time);
}

In this case we basically keep checking the current time against the expiration time. This works and it's also quite precise. The downside of this approach is we are wasting tons of CPU cycles. You can see it clearly if you look at the process utilization:

fn main() {
    let wiat = WaitInAnotherThread::new(Duration::seconds(30));
    println!("wait spin started");
    wiat.wait_spin();
    println!("wait spin completed");
}

In my case the core 8 is completely used by our code. This is similar of what we experienced in part 3.

Spin waits are very accurate but wasteful. Use them for very short waits only or when you do not have alternatives.

Sleep wait

OSs are able to park your thread for a specific amount of time. This is often called sleep. Sleeping a thread basically tells ths OS: "do not schedule my thread for X seconds". So the OS if free to use the available resources for something else (either another thread of your process of another process altogether). Rust supports this using the std::thread::sleep() function. Our code can be:

pub fn wait_blocking(&self) {
    while Utc::now() < self.end_time {
        let delta_sec = self.end_time.timestamp() - Utc::now().timestamp();
        if delta_sec > 0 {
            thread::sleep(::std::time::Duration::from_secs(delta_sec as u64));
        }
    }
    println!("the time has come == {:?}!", self.end_time);
}

Here we try to determine how long the thread should sleep subtracting the expiration time from current time. Since the timestamp() function is not precise we loop as before. Let's try it:

let wiat = WaitInAnotherThread::new(Duration::seconds(30));
println!("wait blocking started");
wiat.wait_blocking();
println!("wait blocking completed");

The behavior will be the same except, this time, our process will not use any CPU at all:

Way better. But is it a Future?

Future

No, it isn't. We haven't implemented the Future trait. So let's do this. Our first, naive approach could be:

impl Future for WaitInAnotherThread {
    type Item = ();
    type Error = Box<Error>;

    fn poll(&mut self) -> Poll<Self::Item, Self::Error> {
        while Utc::now() < self.end_time {
            let delta_sec = self.end_time.timestamp() - Utc::now().timestamp();
            if delta_sec > 0 {
                thread::sleep(::std::time::Duration::from_secs(delta_sec as u64));
            }
        }
        println!("the time has come == {:?}!", self.end_time);
        Ok(Async::Ready(())
}

While this method would not waste CPU cycles it will block the reactor. A blocked reactor does not advance the other futures. Which is bad.

Futures should block as little as possible.

In order to be a good reactor citizen we need to:

Park our task when it's waiting for the expiration time.
Do not block the current thread.
Signal the reactor when the task is completed (expiration time).

What we will do is to create another sleeping thread. This thread will not consume resources because we will put it to sleep. Being in a separate thread the reactor will keep working happily. When the separate thread wakes (after the sleeping time) it will unpark the task, signaling the reactor.

Let's sketch an implementation first and then walk through it:

impl Future for WaitInAnotherThread {
    type Item = ();
    type Error = Box<Error>;

    fn poll(&mut self) -> Poll<Self::Item, Self::Error> {
        if Utc::now() < self.end_time {
            println!("not ready yet! parking the task.");

            if !self.running {
                println!("side thread not running! starting now!");
                self.run(task::current());
                self.running = true;
            }

            Ok(Async::NotReady)
        } else {
            println!("ready! the task will complete.");
            Ok(Async::Ready(()))
        }
    }
}

We need to kick off the parallel thread only once so we use the running field for that. Notice that our execution won't start until the future is polled. This is perfectly fine for our purposes. Also we check if the expiration time is already in the past in which case we do not spawn the side thread at all (we will see the run function in a moment).

If the expiration time is in the future and there is no side thread running we spawn it. We then ask to park our task returning Ok(Async::NotReady). Contrarily to what we did in part 3 we do not unpark the task here. That's responsibility of the side thread. In other implementations, such as IO, it would be an OS responsibility to wake our task.

The side thread code is this one:

fn run(&mut self, task: task::Task) {
    let lend = self.end_time;

    thread::spawn(move || {
        while Utc::now() < lend {
            let delta_sec = lend.timestamp() - Utc::now().timestamp();
            if delta_sec > 0 {
                thread::sleep(::std::time::Duration::from_secs(delta_sec as u64));
            }
            task.notify();
        }
        println!("the time has come == {:?}!", lend);
    });
}

Two things to note here. First we pass to the parallel thread the task reference. This is important because we cannot resort to Task::current() in a separate thread. Secondly, we do not move self into the closure: that's why we bind lend to a self.end_time copy. Why is that? Threads in Rust require the Send trait with the 'static lifetime. the Task complies to both so we can move it into the closure. Our struct does not so we move a copy of the end_time field instead.

This means that you cannot change the expiration time after the thread has been started.

Let's give it a try:

fn main() {
    let mut reactor = Core::new().unwrap();

    let wiat = WaitInAnotherThread::new(Duration::seconds(3));
    println!("wait future started");
    let ret = reactor.run(wiat).unwrap();
    println!("wait future completed. ret == {:?}", ret);
}

This is the output:

    Finished dev [unoptimized + debuginfo] target(s) in 0.96 secs
     Running `target/debug/tst_fut_complete`
wait future started
not ready yet! parking the task.
side thread not running! starting now!
the time has come == 2017-11-21T12:55:23.397862771Z!
ready! the task will complete.
wait future completed. ret == ()

Notice the temporal flow of events:

We ask the rector to start our future
Our future notices the expiration date is in the future so:
1. Parks the task
2. Starts the side thread
The side thread awakens after some time and:
1. Notifies the reactor that the task should be unparked
2. Destroys the side thread (quits)
The reactor awakens the parked task
The future (aka task) completes and:
1. Signals the reactor that it has completed
2. Returns the output value (unit in our case)
The reactor return the output value of the task to the caller of the run function.

Pretty neat, don't you think?

Conclusion

This completes our "real life" future. It does not block so it behaves correctly in a reactor. It does not use unnecessary resources. It also does not do anything useful on its own (besides being used as timeout mechanism, can you imagine how?).

Of course you generally do not write a future manually. You use the ones provided by libraries and compose them as needed. It's important to understand how they work nevertheless.

The next topic will be the Streams which will allow to create Iterators that yield the values one at the time not blocking the reactor while doing so.

Happy Coding

Francesco Cogno

Rust futures: an uneducated, short and hopefully not boring tutorial - Part 3 - The reactor

Francesco Cogno — Wed, 08 Nov 2017 15:31:29 +0000

Intro

In this post we will try and explain how the reactor works. In the previous posts we used it extensively to execute our futures but we treated it as a black box. It's time to shed some light on it!

Reactor? Loop?

A reactor is, in a nutshell, a loop. To explain it I think an analogy is in order. Suppose you have asked a girl/boy to a date using email (yes, I know, it's old-school). You expect an answer so you check your email. And check your email. And check your email. Until, finally, you get your answer.

Rust's reactor is like that. You give it a future and it checks over and over its state until completion (or error). It does that calling a function called, unsurprisingly, poll. It's up to the implementer to write the poll function. All you have to do is to return a Poll<T,E> structure (see Poll docs for more details). In reality the reactor doesn't poll your function endlessly but, for the time being, let's stop here and start with and example.

A future from scratch

In order to test our reactor knowledge we are going to implement a future from scratch. In other words we will implement the Future trait manually. We will implement the simplest future available: one that does not return until a specific time has come.

We are going to call our struct WaitForIt:

#[derive(Debug)]
struct WaitForIt {
    message: String,
    until: DateTime<Utc>,
    polls: u64,
}

Our struct will hold the time to wait for, a custom string message and the number of times it has been polled. To help clean our code we are going to implement the new function too:

impl WaitForIt {
    pub fn new(message: String, delay: Duration) -> WaitForIt {
        WaitForIt {
            polls: 0,
            message: message,
            until: Utc::now() + delay,
        }
    }
}

The new function will create and initialize a WaitForIt instance.

Now we will implement the Future trait. All we are required to do is to supply the poll method:

impl Future for WaitForIt {
    type Item = String;
    type Error = Box<Error>;

    fn poll(&mut self) -> Poll<Self::Item, Self::Error> {
        let now = Utc::now();
        if self.until < now {
            Ok(Async::Ready(
                format!("{} after {} polls!", self.message, self.polls),
            ))
        } else {
            self.polls += 1;

            println!("not ready yet --> {:?}", self);
            Ok(Async::NotReady)
        }
    }
}

Let's go through it in steps. These awkward lines:

    type Item = String;
    type Error = Box<Error>;

are called associated types. They are meant to indicate what the future will return upon completion (or error). So we are saying: our will future will resolve into either a String or a Box<Error>.
This line:

    fn poll(&mut self) -> Poll<Self::Item, Self::Error> {

Defines the poll function. The Self::Item and Self::Error parts are placeholders of the associated types specified earlier. In our case the method reads like: fn poll(&mut self) -> Poll<String, Box<Error>>.

Now our logic will be:

let now = Utc::now();
 if self.until < now {
   // Tell reactor we are ready!
 } else {
   // Tell reactor we are not ready! Come back later!
 }

How can we tell the reactor we aren't finished yet? We return Ok with the Async::NotReady enum. If we are done we return Ok with Async::Ready(T). So our function becomes:

impl Future for WaitForIt {
    type Item = String;
    type Error = Box<Error>;

    fn poll(&mut self) -> Poll<Self::Item, Self::Error> {
        let now = Utc::now();
        if self.until < now {
            Ok(Async::Ready(
                format!("{} after {} polls!", self.message, self.polls),
            ))
        } else {
            self.polls += 1;

            println!("not ready yet --> {:?}", self);
            Ok(Async::NotReady)
        }
    }
}

To run our future we have to create a reactor in main and ask it to run our future implementing struct.

fn main() {
    let mut reactor = Core::new().unwrap();

    let wfi_1 = WaitForIt::new("I'm done:".to_owned(), Duration::seconds(1));
    println!("wfi_1 == {:?}", wfi_1);

    let ret = reactor.run(wfi_1).unwrap();
    println!("ret == {:?}", ret);
}

Now if we run it we expect our future to wait 1 second and then complete. Let's run it:

Running `target/debug/tst_fut_create`
wfi_1 == WaitForIt { message: "I\'m done:", until: 2017-11-07T16:07:06.382232234Z, polls: 0 }
not ready yet --> WaitForIt { message: "I\'m done:", until: 2017-11-07T16:07:06.382232234Z, polls: 1 }

Aaaand... the code will be stuck. Also worth noting is that the process does not consume any CPU:

But why is that? That's the reactor magic: the reactor does not poll a parked function unless explicitly told so. In our case the reactor called our function immediately. We returned Async::NotReady so the reactor parked our function. Unless something unparks our function the reactor will never call it again. While waiting the reactor is basically idle so it does not consume any CPU as shown above. This yields great efficiency as we do not waste CPU cycles asking for completion over and over again. In our email example we could avoid checking the mail manually and wait for a notification instead. So we are free to play Doom in the meantime.

Another more meaningful example could be receiving data from the network. We could block our thread waiting for a network packet or we could do something else while we wait. You might wonder why this approach is better than using OS threads. Long story short, it is often more efficient.

Unparking

But how can we correct our example? We need to unpark our future somehow. Ideally we should have some external event to unpark our future (for example a keypress or a network packet) but for our example we will unpark manually using this simple line:

futures::task::current().notify();

So our future implementation becomes:

impl Future for WaitForIt {
    type Item = String;
    type Error = Box<Error>;

    fn poll(&mut self) -> Poll<Self::Item, Self::Error> {
        let now = Utc::now();
        if self.until < now {
            Ok(Async::Ready(
                format!("{} after {} polls!", self.message, self.polls),
            ))
        } else {
            self.polls += 1;

            println!("not ready yet --> {:?}", self);
            futures::task::current().notify();
            Ok(Async::NotReady)
        }
    }
}

Now let's run the code:

Now the code completes. Notice that, in my case, the function has been called over 50k times in a second! That's a waste of resources and clearly demonstrates why you should unpark your future only when something happened. This is evident looking and the CPU consumption of our process:

Note also how the loop consumes only a single thread. This is by design and one of the sources of efficiency. You can, of course, use more threads if necessary.

Joining

An useful feature of reactors is the ability to run multiple futures concurrently. This is how we harness the efficiency of the single thread loop: when a future is parked, another one can proceed.

For this example we are going to reuse our WaitForIt struct. We just call it twice at the same time. We start creating two instances of our future:

let wfi_1 = WaitForIt::new("I'm done:".to_owned(), Duration::seconds(1));
println!("wfi_1 == {:?}", wfi_1);
let wfi_2 = WaitForIt::new("I'm done too:".to_owned(), Duration::seconds(1));
println!("wfi_2 == {:?}", wfi_2);

Now we can call the futures::future::join_all function. The join_all function expects an iterator with our futures. For our porpuses a simple vector will do:

let v = vec![wfi_1, wfi_2];

The join_all function returns, basically, an enumerable with the resolved futures.

let sel = join_all(v);

So our complete code will be:

fn main() {
    let mut reactor = Core::new().unwrap();

    let wfi_1 = WaitForIt::new("I'm done:".to_owned(), Duration::seconds(1));
    println!("wfi_1 == {:?}", wfi_1);
    let wfi_2 = WaitForIt::new("I'm done too:".to_owned(), Duration::seconds(1));
    println!("wfi_2 == {:?}", wfi_2);

    let v = vec![wfi_1, wfi_2];

    let sel = join_all(v);

    let ret = reactor.run(sel).unwrap();
    println!("ret == {:?}", ret);
}

Now let's run it. The output will be something like this:

The key point here is that the two requests are interleaved: the first future is called, then the second, then the first and so on until both are completed. As you can see in the above image, the first future completed before the second one. Also the second one gets called twice before coming to completion.

Select

There are many more functions in the future trait. Another thing worth exploring here is the select function. The select function runs two (or more in case of select_all) futures and returns the first one coming to completion. This is useful for implementing timeouts. Our example can simply be:

fn main() {
    let mut reactor = Core::new().unwrap();

    let wfi_1 = WaitForIt::new("I'm done:".to_owned(), Duration::seconds(1));
    println!("wfi_1 == {:?}", wfi_1);
    let wfi_2 = WaitForIt::new("I'm done too:".to_owned(), Duration::seconds(2));
    println!("wfi_2 == {:?}", wfi_2);

    let v = vec![wfi_1, wfi_2];

    let sel = select_all(v);

    let ret = reactor.run(sel).unwrap();
    println!("ret == {:?}", ret);
}

Closing remarks

In the part 4 we will create a more "real life" future: one that does not use CPU resources needlessly and behaves as expected when used in a reactor.

Happy coding,

Francesco Cogno

Rust futures: an uneducated, short and hopefully not boring tutorial - Part 2

Francesco Cogno — Fri, 03 Nov 2017 09:00:38 +0000

Intro

In the first post of the series we saw how to use futures in Rust. They are powerful and very easy to use, if done properly. In this second post we will focus on common pitfalls and, hopefully, how to avoid them.

Error troubles

Chaining futures is easy. We saw how to exploit the and_then() function to do it. But in the previous part we cheated using the Box<Error> trait as error type. Why haven't I used a more specific error type? It turns out when you chain futures you must return always the same error type.

While chaining futures the error type must be the same.

Let's try and demonstrate this.

We have two types, called ErrorA and ErrorB (yes, I know, not terribly original). We will implement the error::Error trait even though is not strictly necessary (but it's good practice IMHO). The Error trait requires std::fmt::Display too so we're going to implement that trait as well.

#[derive(Debug, Default)]
pub struct ErrorA {}

impl fmt::Display for ErrorA {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "ErrorA!")
    }
}

impl error::Error for ErrorA {
    fn description(&self) -> &str {
        "Description for ErrorA"
    }

    fn cause(&self) -> Option<&error::Error> {
        None
    }
}

ErrorB is the same:

#[derive(Debug, Default)]
pub struct ErrorB {}

impl fmt::Display for ErrorB {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "ErrorB!")
    }
}

impl error::Error for ErrorB {
    fn description(&self) -> &str {
        "Description for ErrorB"
    }

    fn cause(&self) -> Option<&error::Error> {
        None
    }
}

I've kept the implementations simple to prove my point. Now let's use these structs in out futures. Remember, a future it's just a Result<A,B> returning function with a slight different syntax.

fn fut_error_a() -> impl Future<Item = (), Error = ErrorA> {
    err(ErrorA {})
}

fn fut_error_b() -> impl Future<Item = (), Error = ErrorB> {
    err(ErrorB {})
}

Now let's call them in our main function:

let retval = reactor.run(fut_error_a()).unwrap_err();
println!("fut_error_a == {:?}", retval);

let retval = reactor.run(fut_error_b()).unwrap_err();
println!("fut_error_b == {:?}", retval);

The result is, unsurprisingly:

fut_error_a == ErrorA
fut_error_b == ErrorB

So far so good. Now let's try to chain these futures:

let future = fut_error_a().and_then(|_| fut_error_b());

What we are doing here is to call the fut_error_a function and then call fut_error_b one. We do not care about the value returned by fut_error_a so we discard it with an underscore.
In more complex terms we want to chain a impl Future<Item=(), Error=ErrorA> with a impl Future<Item=(), Error=ErrorB>.

Let's try and compile it:

Compiling tst_fut2 v0.1.0 (file:///home/MINDFLAVOR/mindflavor/src/rust/tst_future_2)
error[E0271]: type mismatch resolving `<impl futures::Future as futures::IntoFuture>::Error == errors::ErrorA`
   --> src/main.rs:166:32
    |
166 |     let future = fut_error_a().and_then(|_| fut_error_b());
    |                                ^^^^^^^^ expected struct `errors::ErrorB`, found struct `errors::ErrorA`
    |
    = note: expected type `errors::ErrorB`
               found type `errors::ErrorA`

The error is clear. We should have used a ErrorB. We supplied an ErrorA instead. In general terms:

When chaining futures, the first function error type must be the same as the chained one.

That's exactly what rustc is telling us. The chained function return a ErrorB so the first function must return a ErrorB too. It does not (it returns a ErrorA instead) so the compilation fails.

How can we handle this problem? Fortunately there is a chainable method called map_err we can use. In our example we want to convert the ErrorA in ErrorB so we inject this function call between the two futures:

let future = fut_error_a()
    .map_err(|e| {
        println!("mapping {:?} into ErrorB", e);
        ErrorB::default()
    })
    .and_then(|_| fut_error_b());

let retval = reactor.run(future).unwrap_err();
println!("error chain == {:?}", retval);

If we compile now and run the sample this will be the output:

mapping ErrorA into ErrorB
error chain == ErrorB

Let's push the example further. Suppose we want to chain ErrorA, then ErrorB and then ErrorA again. Something like:

let future = fut_error_a()
    .and_then(|_| fut_error_b())
    .and_then(|_| fut_error_a());

The rule clearly works on pairs. It does not account for the whole composition. So we have to map the error in ErrorB between fut_error_a and fut_error_b and then the other way around: map ErrorA between fut_error_b and fut_error_a. Hideous but working:

let future = fut_error_a()
    .map_err(|_| ErrorB::default())
    .and_then(|_| fut_error_b())
    .map_err(|_| ErrorA::default())
    .and_then(|_| fut_error_a());

"From" to the rescue

One way to simplify the above code is to exploit the std::convert::From trait. Basically with the From trait you can tell Rust how to convert one struct into another automagically. The trait consumes the original error which is fine in our implementation. Also the trait assumes the conversion does not fail. Lastly, we can only implement traits for structs we own - ie written by us - so this approach cannot always be used.

Let's implement From<ErrorA> for ErrorB and FromInto<ErrorB> for ErrorA:

impl From<ErrorB> for ErrorA {
    fn from(e: ErrorB) -> ErrorA {
        ErrorA::default()
    }
}

impl From<ErrorA> for ErrorB {
    fn from(e: ErrorA) -> ErrorB {
        ErrorB::default()
    }
}

Now the previous code can be simplified by just calling the from_err() function instead of map_err(). Rust will be smart enough to figure out which conversion to use on its own:

let future = fut_error_a()
   .from_err()
   .and_then(|_| fut_error_b())
   .from_err()
   .and_then(|_| fut_error_a());

The code is still intermingled with error conversion but the conversion code is no longer inline. This helps the readability of your code considerably.
The Future crate is clever: the from_err code will be called only in case of errors so there is no runtime penalty of using it.

Lifetimes

Rust signature feature is the explicit lifetime annotation of references. Most of the time, however, Rust allows us to avoid to specify the lifetime using lifetime elision. Let's see it in action. We want to code a function that takes a string reference and return, if successful, the same string reference:

fn my_fn_ref<'a>(s: &'a str) -> Result<&'a str, Box<Error>> {
    Ok(s)
}

Notice the <'a> part. We are declaring a lifetime. Then with s: &'a str we are creating a parameter that will accept string references that must be valid for as long as 'a is valid. With the Result<&' str, Box<Error>> we are telling Rust that our return value will contain a string reference. That string reference must be valid as long as 'a is valid. In other words the passed string reference and the returned object must have the same lifetime.

That said this syntax is so verbose that Rust allows us to avoid specifying lifetimes in common case such as this. So we can rewrite the function this way:

fn my_fn_ref(s: &str) -> Result<&str, Box<Error>> {
    Ok(s)
}

Notice there is no longer a mention to lifetimes, even though they are there. This function declaration is much simpler to understand at glance.

But... you cannot elide lifetimes when working with futures (yet). If you try to convert this function to the same impl Future one as we did in the previous blog post:

fn my_fut_ref_implicit(s: &str) -> impl Future<Item = &str, Error = Box<Error>> {
    ok(s)
}

You will get an error. In my case (using rustc 1.23.0-nightly (2be4cc040 2017-11-01)) I've got a compiler panic:

   Compiling tst_fut2 v0.1.0 (file:///home/MINDFLAVOR/mindflavor/src/rust/tst_future_2)
error: internal compiler error: /checkout/src/librustc_typeck/check/mod.rs:633: escaping regions in predicate Obligation(predicate=Binder(ProjectionPredicate(ProjectionTy { substs: Slice([_]), item_def_id: DefId { krate: CrateNum(15), index: DefIndex(0:330) => futures[59aa]::future[0]::Future[0]::Item[0] } }, &str)),depth=0)
  --> src/main.rs:39:36
   |
39 | fn my_fut_ref_implicit(s: &str) -> impl Future<Item = &str, Error = Box<Error>> {
   |                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

note: the compiler unexpectedly panicked. this is a bug.

note: we would appreciate a bug report: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#bug-reports

note: rustc 1.23.0-nightly (2be4cc040 2017-11-01) running on x86_64-unknown-linux-gnu

thread 'rustc' panicked at 'Box<Any>', /checkout/src/librustc_errors/lib.rs:450:8
note: Run with `RUST_BACKTRACE=1` for a backtrace.

Don't fret on it, remember impl Future is still a nightly-only feature. To solve it we just have to avoid lifetime elision by explicitly annotating the references with lifetimes:

fn my_fut_ref<'a>(s: &'a str) -> impl Future<Item = &'a str, Error = Box<Error>> {
    ok(s)
}

This will work as expected.

impl Future with lifetimes

The need to explicitly express the lifetimes goes beyond the parameters. If you return an impl Future constrained by a lifetime you have to annotate it as well. For example suppose we want to return a future String from a function taking a &str as parameter. We know we must annotate the parameter with lifetimes so we might try this:

fn my_fut_ref_chained<'a>(s: &'a str) -> impl Future<Item = String, Error = Box<Error>> {
    my_fut_ref(s).and_then(|s| ok(format!("received == {}", s)))
}

This will not work: the returned future is not constrained by 'a. The error is:

error[E0564]: only named lifetimes are allowed in `impl Trait`, but `` was found in the type `futures::AndThen<impl futures::Future, futures::FutureResult<std::string::String, std::boxed::Box<std::error::Error + 'static>>, [closure@src/main.rs:44:28: 44:64]>`
  --> src/main.rs:43:42
   |
43 | fn my_fut_ref_chained<'a>(s: &'a str) -> impl Future<Item = String, Error = Box<Error>> {
   |                                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To solve the error all you have to do is to append 'a to the impl Future declaration, like this:

fn my_fut_ref_chained<'a>(s: &'a str) -> impl Future<Item = String, Error = Box<Error>> + 'a {
    my_fut_ref(s).and_then(|s| ok(format!("received == {}", s)))
}

Credit goes to HadrienG for this. See Trouble with named lifetimes in chained futures.

Now you can call the function using your reactor as usual:

let retval = reactor
    .run(my_fut_ref_chained("str with lifetime"))
    .unwrap();
println!("my_fut_ref_chained == {}", retval);

And get the expected output:

my_fut_ref_chained == received == str with lifetime

Closing remarks

In the next post we will cover the reactor. We will also write a future implementing struct from scratch.

Happy Coding,
Francesco Cogno

Rust futures: an uneducated, short and hopefully not boring tutorial - Part 1

Francesco Cogno — Tue, 24 Oct 2017 14:15:26 +0000

Intro

If you are a programmer and you like Rust you might be aware of the future movement that is buzzing around the Rust community. Great crates have embraced it fully (for example Hyper) so we must be able to use it. But if you are an average programmer like me you may have an hard time understanding them. Sure there is the official Crichton's tutorial but, while being very thorough, I've found it very hard to put in practice.

I'm guessing I'm not the only one so I will share my findings hoping they will help you to become more proficient with the topic.

Futures in a nutshell

Futures are peculiar functions that do not execute immediately. They will execute in the future (hence the name). There are many reasons why we might want to use a future instead of a standard function: performance, elegance, composability and so on. The downside is they are hard to code. Very hard. How can you understand causality when you don't know when a function is going to be executed?

For that reason programming languages have always tried to help us poor, lost programmers with targeted features.

Rust's futures

Rust's future implementation, true to its meme, is a work in progress. So, as always, what are you reading can already be obsolete. Handle with care.

Rust's futures are always Results: that means you have to specify both the expected return type and the alternative error one.

Let's pick a function and convert it to future. Our sample function returns either u32 or a Boxed Error trait. Here it is:

fn my_fn() -> Result<u32, Box<Error>> {
    Ok(100)
}

Very easy. Not look at the relative future implementation:

fn my_fut() -> impl Future<Item = u32, Error = Box<Error>> {
    ok(100)
}

Notice the differences. First the return type is no longer a Result but a impl Future. That syntax (still nightly-only at the time of writing) allows us to return a future. The <Item = u32, Error = Box<Error>> part is just a more verbose way of detailing the returned type and the error type as before.

You need the conservative_impl_trait nightly feature for this to work. You can return a boxed trait instead but it's more cumbersome IMHO.

Notice also the case of the Ok(100) returned value. In the Result function we use the capitalized Ok enum, in the future one we use the lowercase ok method.

Rule of the thumb: use lowercase return methods in futures.

All in all is not that bad. But how can we execute it? The standard function can be called directly. Note that since we are returning a Result we must unwrap() to get the inner value.

let retval = my_fn().unwrap();
println!("{:?}", retval);

As futures return before actually executing (or, more correctly, we are returning the code to be executed in the future) we need a way to run it. For that we use a Reactor. Just create it and call its run method to execute a future. In our case:

let mut reactor = Core::new().unwrap();

let retval = reactor.run(my_fut()).unwrap();
println!("{:?}", retval);

Notice here we are unwrapping the run(...) return value, not the my_fut() one.

Really easy.

Chaining

One of the most powerful features of futures is the ability to chain futures together to be executed in sequence. Think about inviting your parents for dinner via snake mail. You send them a mail and then wait for their answer. When you get the answer you proceed preparing the dinner for them (or not, claiming sudden crippling illness). Chaining is like that. Let's see an example.

First we add another function, called squared both as standard and future one:

fn my_fn_squared(i: u32) -> Result<u32, Box<Error>> {
    Ok(i * i)
}


fn my_fut_squared(i: u32) -> impl Future<Item = u32, Error = Box<Error>> {
    ok(i * i)
}

Now we might call the plain function this way:

let retval = my_fn().unwrap();
println!("{:?}", retval);

let retval2 = my_fn_squared(retval).unwrap();
println!("{:?}", retval2);

We could simulate the same flow with multiple reactor runs like this:

let mut reactor = Core::new().unwrap();

let retval = reactor.run(my_fut()).unwrap();
println!("{:?}", retval);

let retval2 = reactor.run(my_fut_squared(retval)).unwrap();
println!("{:?}", retval2);

But there is a better way. A future, being a trait, has many methods (we will cover some here). One, called and_then, does exactly what we coded in the last snippet but without the explicit double reactor run. Let's see it:

let chained_future = my_fut().and_then(|retval| my_fn_squared(retval));
let retval2 = reactor.run(chained_future).unwrap();
println!("{:?}", retval2);

Look at the first line. We have created a new future, called chained_future composed by my_fut and my_fut_squared.

The tricky part is how to pass the result from one future to the next. Rust does it via closure captures (the stuff between pipes, in our case |retval|). Think about it this way:

Schedule the execution of my_fut().
When my_fut() ends create a variable called retval and store into it the result of my_fut() execution.
Now schedule the execution of my_fn_squared(i: u32) passing retval as parameter.
Package this instruction list in a future called chained_future.

The next line is similar as before: we ask the reactor to run chained_future instruction list and give us the result.

Of course we can chain an endless number of method calls. Don't worry about performance either: your future chain will be zero cost (unless you Box for whatever reason).

The borrow checked may give you an hard time in the capture chains. In that case try moving the captured variable first with move.

Mixing futures and plain functions

You can chain futures with plain functions as well. This is useful because not every function needs to be a future. Also you might want to call external function over which you have no control.

If the function does not return a Result you can simply add the function call in the closure. For example, if we have this plain function

fn fn_plain(i: u32) -> u32 {
    i - 50
}

Our chained future could be:

let chained_future = my_fut().and_then(|retval| {
    let retval2 = fn_plain(retval);
    my_fut_squared(retval2)
});
let retval3 = reactor.run(chained_future).unwrap();
println!("{:?}", retval3);

If your plain function returns a Result there is a better way. Let's chain our my_fn_squared(i: u32) -> Result<u32, Box<Error>> function.

You cannot call and_then to a Result but the futures create have you covered! There is a method called done that converts a Result into a impl Future.
What does that means to us? We can wrap our plain function in the done method and than we can treat it as if it were a future to begin with!

Let's try it:

let chained_future = my_fut().and_then(|retval| {
    done(my_fn_squared(retval)).and_then(|retval2| my_fut_squared(retval2))
});
let retval3 = reactor.run(chained_future).unwrap();
println!("{:?}", retval3);

Notice the second line: done(my_fn_squared(retval)) allows us to chain a plain function as it were a impl Future returning function. Now try without the done function:

let chained_future = my_fut().and_then(|retval| {
    my_fn_squared(retval).and_then(|retval2| my_fut_squared(retval2))
});
let retval3 = reactor.run(chained_future).unwrap();
println!("{:?}", retval3);

The error is:

   Compiling tst_fut2 v0.1.0 (file:///home/MINDFLAVOR/mindflavor/src/rust/tst_future_2)
error[E0308]: mismatched types
   --> src/main.rs:136:50
    |
136 |         my_fn_squared(retval).and_then(|retval2| my_fut_squared(retval2))
    |                                                  ^^^^^^^^^^^^^^^^^^^^^^^ expected enum `std::result::Result`, found anonymized type
    |
    = note: expected type `std::result::Result<_, std::boxed::Box<std::error::Error>>`
               found type `impl futures::Future`

error: aborting due to previous error

error: Could not compile `tst_fut2`.

The expected type std::result::Result<_, std::boxed::Box<std::error::Error>> found type impl futures::Future is somewhat misleading. In fact we were supposed to pass an impl Future and we used a Result instead (not the other way around). This kind of confusion is common using futures (see https://github.com/alexcrichton/futures-rs/issues/402). We'll talk about it in the second part of the post.

Generics

Last but not least, futures work with generics without any magic.

Let's see an example:

fn fut_generic_own<A>(a1: A, a2: A) -> impl Future<Item = A, Error = Box<Error>>
where
    A: std::cmp::PartialOrd,
{
    if a1 < a2 {
        ok(a1)
    } else {
        ok(a2)
    }
}

This function returns the smaller parameter passed. Remember, we need to give and Error even if no error is expected in order to implement the Future trait. Also, the return values (ok in this case) are lowercase (the reason is ok being a function, not an enum).

Now we can run the future as always:

let future = fut_generic_own("Sampdoria", "Juventus");
let retval = reactor.run(future).unwrap();
println!("fut_generic_own == {}", retval);

I hope you got the gist by now :). Until now it should make sense. You may ave noticed I avoided using references and used owned values only. That's because lifetimes do not behave the same using impl Future. I will explain how to use address them in the next post. In the next post we will also talk about error handling in chains and about the await! macro.

Notes

If you want to play with these snippets you just need to add in your Cargo.toml file:

[dependencies]
futures="*"
tokio-core="*"
futures-await = { git = 'https://github.com/alexcrichton/futures-await' }

And put these lines on top of src/main.rs:

#![feature(conservative_impl_trait, proc_macro, generators)]

extern crate futures_await as futures;
extern crate tokio_core;

use futures::done;
use futures::prelude::*;
use futures::future::{err, ok};
use tokio_core::reactor::Core;
use std::error::Error;

The `futures-await` crate is not really needed for this post but we will use it in the next one.

Happy coding,
Francesco Cogno