So, lifetime parameters seem to be a big source of confusion for new Rustaceans; I don't think that's news to anyone. And I'm sure better documentation will be coming at some point. But I know that people who have gained a thorough understanding of a difficult topic often lose sight of how the topic is difficult for others. So I just want to outline the points that I personally feel need clarification. I think some of these things are already somewhat documented, but may need to be stated more explicitly or illustrated with examples.
Is a lifetime parameter an order to the compiler, or just a suggestion?
It is self-evident that a lifetime has a beginning and an end. But what exactly does a lifetime parameter (in a given position in the code) say about that beginning and end?
When an object or function has multiple lifetimes associated with it (e.g. a struct type containing members with different lifetimes), does one lifetime take precedence over others? Is there a straightforward way to determine which one that is?
When a lifetime is declared in a particular context (e.g. a function signature), how does that affect the behavior of the associated objects in other contexts (e.g. in the calling function).
Is it possible to state any general guidelines about where lifetimes should be declared and to which objects they should be attached?
Still a little confused by lifetimes myself so hopefully this is helpful:
This maybe in the docs somewhere but one aspect I still find
confusing are traits such as Foo + 'a vs Foo<'a>.
An example of how generic seem to fill lifetimes in. Maybe some illustrative cases where you would want separate life times for fields inside a struct?
When things might be 'static outside of literals. It looks like Any can only deal with static. I imagine there must be way around this otherwise the Any trait would be pretty useless.
More examples of how to use the standard library would also help. I spent an entire afternoon trying to figure out how to pass my Peekable iterators into other functions in a recursive decent parser. Most of this was due to lifetimes. I imagine one example there would have saved me a lot of time.
An idea I had the other day that would be neat is some a tool that could diagram out the life times in a visual way. Maybe use circles to denote lifetimes?
Another reddit where there is confusion over the fact that lifetime annotation doesn't control the lifetime length. It just describes it for the compiler.
Sorta. The beta lifetime guide has some info but questions come up a lot about them and they haven't been addressed by the docs. The nightly is in flux because the table of contents is being shuffled. Until the issues with lifetimes are addressed, IRC and various threads on reddit/stackoverflow/whatever will be the standard resource.
Because these issues are so common though, a lot can be learned just by lurking in the meantime. Eventually the docs will catch up (at least that's the hope).
@mgushee@robo_hamburger@swuecho@killkrt I put up a WIP PR for rustbyexample about lifetimes. I have tried to address most of the questions I could find here in this thread but I'm not sure what's being asked some of the time.
If you think I missed something big, you should comment about it. Maybe it'll be easy to fix.