Trying to improve the documentation for App::data()

[lfrancke]

PR Type

Other (Documentation only)

PR Checklist

Check your PR fulfills the following:

• Documentation comments have been added / updated.

Overview

This is related to the discussion in #1454 which aims to eventually change the semantics of data and/or app_data. In the meantime I found the documentation very confusing and in this PR I'm trying to clarify what's going on.

That said: I still don't fully understand it so I set it as a draft PR and am looking for feedback on what might be changed.

My main open question is why data wraps in an Arc at all.
I'm new to Rust so I might be missing very obvious things but by my understanding Actix runs the application factory closure once per thread it instantiates so the data does not need to be Send because it's instantiated in the target thread and it doesn't need to be Sync (by default) either, no?

If anyone could help clarify I'd try to adopt the documentation.

[JohnTitor]

Oh, nightly encounters an ICE, I believe that's rust-lang/rust#77993.

[fakeshadow]

extract Data in handler would require a Clone. That's the main reason it's a smart pointer so what inside the Data can be a not cloneable type. Arc is a reasonable choice as the cost is not big in single thread(almost no contetion) and it can be moved to other threads easily if you ever want to in your handler(like pass it to threadpool or a future moved to other threads).
It all comes down to let user pass a cloneable type to Data or the framework do it for them with a low cost wrapper.

[lfrancke]

Thank you @fakeshadow, that is very helpful. I never looked at it that way. I'll try to adjust the docs.

Also thanks @JohnTitor I was a bit surprised that my docs-only change causes a failure.

[robjtede]

Is this true, or is it the last invocation is used?

[lfrancke]

I did look at the code back then and I thought this is what it does but I can take another look.

[lfrancke]

I have to be honest: I don't understand (anymore) how this is used. If one of you has any insights I'll happily add it otherwise I'd just remove that sentence.

It would be good to document the behavior though.

[robjtede]

You know what you're right, and that's surprising behavior actually because .app_data works differently; a bug, even.

[lfrancke]

Out of curiosity (because I couldn't trace it anymore but I know I did in the past): Can you point me at the location where this happens?