This post examines a particular, seemingly simple problem: given ownership of a Rc<Vec<u32>>, can we write a function that returns an impl Iterator<Item = u32>? It turns out that this is a bit harder than it might at first appear – and, as we’ll see, for good reason. I’ll dig into what’s going on, how you can fix it, and how we might extend the language in the future to try and get past this challenge.

The goal

To set the scene, let’s take a look at a rather artifical function signature. For whatever reason, this function has to take ownership of an Rc<Vec<u32>> and it wants to return an impl Iterator<Item = u32>1 that iterates over that vector.

fn iterate(data: Rc<Vec<u32>>) -> impl Iterator<Item = u32> {
    ... // what we want to write!
}

(This post was inspired by a problem we hit in the NLL working group. The details of that problem were different – for example, the vector in question was not given as an argument but instead cloned from another location – but this post uses a simplified example so as to focus on interesting questions and not get lost in other details.)

First draft

The first thing to notice is that our function takes ownership of a Rc<Vec<u32>> – that is, a reference counted2 vector of integers. Presumably, this vector is reference counted because it is shared amongst many places.

The fact that we have ownership of a Rc<Vec<u32>> is precisely what makes our problem challenging. If the function were taking a Vec<u32>, it would be rather trivial to write: we could invoke data.into_iter() and be done with it (try it on play).

Alternatively, if the function took a borrowed vector of type &Vec<u32>, there would still be an easy solution. In that case, we couldn’t use into_iter, because that requires ownership of the vector. But we could write data.iter().cloned()data.iter() gives us back references (&u32) and the cloned() adapter then “clones” them to give us back a u32 (try it on play).

But we have a Rc<Vec<u32>>, so what can we do? We can’t invoke into_iter, since that requires complete ownership of the vector, and we only have partial ownership (we share this same vector with whoever else has an Rc handle). So let’s try using .iter().cloned(), like we did with the shared reference:

// First draft
fn iterate(data: Rc<Vec<u32>>) -> impl Iterator<Item = u32> {
    data.iter().cloned()
}

If you try that on playground, you’ll find you get this error:

error[E0597]: `data` would be dropped while still borrowed
 --> src/main.rs:4:5
   |
 4 |     data.iter().cloned()
   |     ^^^^ borrowed value does not live long enough
 5 | }
   | - borrowed value only lives until here
   |
   = note: borrowed value must be valid for the static lifetime...

This error is one of those frustrating error messages – it says exactly what the problem is, but it’s pretty hard to understand. (I’ve filed #53882 to improve it, though I’m not yet sure what I think it should say.) So let’s dig in to what is going on.

iter() borrows the collection it is iterating over

Fundamentally, the problem here is that when we invoke iter, it borrows the variable data to create a reference (of type &[u32]). That reference is then part of the iterator that is getting returned. The problem is that the memory that this reference refers to is owned by the iterate function, and when iterate returns, that memory will be freed. Therefore, the iterator we give back to the caller will refer to invalid memory.

If we kind of ‘inlined’ the iter call a bit, what’s going on would look like this:

fn iterate(data: Rc<Vec<u32>>) -> impl Iterator<Item = u32> {
    let iterator = Iterator::new(&data); // <-- call to iter() returns this
    let cloned_iterator = ClonedIterator::new(iterator); <-- call to cloned()
    cloned_iterator
}

Here you can more clearly see that data is being borrowed in the first line.

drops in Rust are deterministic

Another crucial ingredient is that the local variable data will be “dropped” when iterate returns. “Dropping” a local variable means two things:

  • We run the destructor, if any, on the value within.
  • We free the memory on the stack where the local variable is stored.

Dropping in Rust proceeds at fixed point. data is a local variable, so – unless it was moved before that point – it will be dropped when we exit its scope. (In the case of temporary values, we use a set of syntactic rules to decide its scope.) In this case, data is a parameter to the function iterate, so it is going to be dropped when iterate returns.

Another key thing to understand is that the borrow checker does not “control” when drops happen – that is controlled entirely by the syntactic structure of the code.3 The borrow checker then comes after and looks to see what could go wrong if that code were executed. In this case, it seems that we have a reference to data that will be returned, but – during the lifetime of that reference – data will be dropped. That is bad, so it gives an error.

What is the fundamental problem here?

This is actually a bit of a tricky problem to fix. The problem here is that Rc<Vec<u32>> only has shared ownership of the Vec<u32> within – therefore, it does not offer any API that will return you a Vec<u32> value. You can only get back &Vec<u32> values – that is, references to the vector inside.

Furthermore, the references you get back will never be able to outlive the Rc<Vec<u32>> value they came from! That is, they will never be able to outlive data. The reason for this is simple: once data gets dropped, those references might be invalid.

So what all of this says is that we will never be able to return an iterator over data unless we can somehow transfer ownership of data back to our caller.

It is interesting to compare this example with the alternative signatures we looked at early on:

  • If iterate took a Vec<u32>, then it would have full ownership of the vector. It can use into_iter to transfer that ownership into an iterator and return the iterator. Therefore, ownership was given back to the caller.
  • If iterate took a &Vec<u32>, it never owned the vector to begin with! It can use iter to create an iterator that references into that vector. We can return that iterator to the caller without incident because the data it refers to is owned by the caller, not us.

How can we fix it?

As we just saw, to write this function we need to find some way to give ownership of data back to the caller, while still yielding up an iterator. One way to do it is by using a move closure, like so (playground):

fn iterate(data: Rc<Vec<u32>>) -> impl Iterator<Item = u32> {
    let len = data.len();
    (0..len).map(move |i| data[i])
}

So why does this work? In the first line, we just read out the length of the data vector – note that, in Rust, any vector stored in a Rc is also immutable (only a full owner can mutate a vector), so we know that this length can never change. Now that we have the length len, we can create an iterator 0..len over the integers from 0 to len. Then we can map from each index i to the data using data[i] – since the data inside is just an integer, it gets copied out.

In terms of ownership, the key point is that here the closure is taking ownership of data. The closure is then placed into the iterator, and the iterator is returned. So indeed ownership of the vector is passing back to the caller as part of the iterator.

What about if I don’t have integers?

You could use the same trick to return an iterator of any type, but you must be able to clone it. For example, you could iterate over strings (playground):

fn iterate(data: Rc<Vec<String>>) -> impl Iterator<Item = String> {
    let len = data.len();
    (0..len).map(move |i| data[i].clone())
}

Why is it important that we clone it? Why can’t we return references? This falls out from how the Iterator trait is designed. If you look at the definition of iterator, it states that it gives ownership of each item that it iterates over:

trait Iterator {
    type Item;
    fn next<'s>(&'s self) -> Option<Self::Item>;
    //           ^^ This would normally be written
    //           `&self`, but I'm giving it a name
    //           so I can refer to it below.
}

In particular, the next function borrows self only for the duration of the call to next. Self::Item, the return type, does not mention the lifetime 's of the self reference, so it cannot borrow from self. This means that I can write generic code where we extract an item, drop the iterator, and then go on using the item:

fn dump_first<I>(some_iter: impl Iterator<Item = I>)
where
    I: Debug,
{
    // Get an item from the iterator.
    let item = some_iter.next();
    
    // Drop the iterator early.
    std::mem::drop(some_iter);
    
    // Keep using the item.
    println!("{:?}", item);
}

Now, imagine what would happen it we permitted the closure to return move |i| &data[i] and we then passed the resulting iterator to dump_first:

  1. We would first extract a reference into data and store it in item.
  2. We would then drop the iterator, which in turn would drop data, potentially freeing the vector (if this is the last Rc handle).
  3. Finally, we would then go on to use item, which has a reference into the (now possibly freed) vector.

So, the lesson is: if you want to return an iterator over borrowed data, per the design of the Iterator trait, you must be iterating over a borrowed reference to begin with (i.e., iterate would need to take a &Rc<Vec<u32>>, &Vec<u32>, or &[u32]).

How could we extend the language to help here?

Self references

This is an interesting question. If we focus just on the original problem – that is, how to return an impl Iterator<Item = u32> – then most obvious thing is the idea of extending the lifetime system to permit “self-references” – for example, it would be nice if you could have a struct that owns some data (e.g., our Rc<Vec<u32>>) and also had a reference into that data (e.g., the result of invoking iter). This might allow us a nicer way of writing the solution to our original problem (returning an impl Iterator<Item = u32>). In particular, what we effectively did in our solution was to use an integer as a kind of “reference” into the vector – each step, we index again. Since indexing is very cheap, this is fine for iterating over a vector, but it wouldn’t work with (say) a Rc<HashMap<K, V>>.

My personal hope is that once we wrap up work on the MIR borrow-checker (NLL) – and we are starting to get close! – we can start to think about self-references and how to model them in Rust. I’d like to transition to a Polonius-based system first, though.

Auxiliary values

Another possible direction that has been kicked around is having some way for a function to return data that its caller must store, which can then be referenced by the “real” return value. The idea would be that iterate would somehow “store” the Rc<Vec<u32>> into its caller’s stack frame, and then return an iterator over that. Ultimately, this is very similar to the “self-reference” concept: the difference is that, with self-references, iterate has to return one value that stores both the Rc<Vec<u32>> and the iterator over it. With this “store data in caller” approach, iterate would return just the iterator, but would specify that the iterator borrows from this other value (the Rc<Vec<u32>>) which is returned in a separate channel.

Interestingly, this idea of returning “auxiliary” values might permit us to return an iterator that gives back references – even though I said that was impossible, per the design of the Iterator trait. How could that work? Well, the problem fundamentally is that we want a signature like this, where the iterator yields up &T references:

fn iterate<T>(data: Rc<Vec<T>>) -> impl Iterator<Item = &T>

Right now, we can’t have this signature, because we have no lifetime to assign to the &T type. In particular, the answer to the question “where are those references borrowing from?” is that they are borrowing from the function iterate itself, which won’t work (as we’ve seen).

But if we had some “auxiliary” slot of data that we could fill and then reference, we might be able to give it a lifetime – let’s call it 'aux. Then we could return impl Iterator<Item = &'aux T>.

Anyway, this is just wild, irresponsible speculation. I don’t have concrete ideas for how this would work4. But it’s an interesting thought.

Discussion

I’ve opened a users thread to discuss this blog post (along with other Rust pattern blog posts).

Footnotes

  1. This just means it wants to return “some iterator that yields up u32 values”.

  2. Also worth nothing: in Rust, reference counted data is typically immutable.

  3. In other words, lifetime inference doesn’t affect execution order. This is crucial – for example, it is the reason we can move to NLL without breaking backwards compatibility.

  4. In terms of the underlying semantics, though, I imagine it could be a kind of sugar atop either self-references or out pointers. But that’s sort of as far as I got. =)