actix-website

actix-website copied to clipboard

The example the Server Basics are as follows right now:

use actix_web::{web, App, HttpResponse, HttpServer};

fn main() {
    let sys = actix_rt::System::new("example");

    HttpServer::new(|| {
        App::new().route("/", web::get().to(|| HttpResponse::Ok()))
    })
    .bind("127.0.0.1:8088")
    .unwrap()
    .start();

    let _ = sys.run();
}

This is the first time actix_rt usage comes up. This was my experience:

1. Thought I might have missed something. went back through the previous tutorials using ctrl-f
2. Nothing came up, so searched the names of the example folders
3. Did a google search. Saw that it was in independent crate
4. went to crates.io - saw it was actix runtime
5. added as Cargo.toml dependency and used the crate.
6. It now works.

Unfortunately, I'm using it, even though I don't understand what its purpose is beyond a somewhat educate guess.

I would suggest that the reader be shown what to do, so they don't have to do the same. I also think it might be important to briefly mention the purpose of the runtime, even if it's just "For now, just know that the server needs this runtime. We cover it in more depth in "

I'm not familiar enough with actix to know what a fix might be, hence the lack of PR. I'm keen to participate how I can though

(updated by @JohnTitor, re-formatted)

We should add a note to explain what's actix-rt in brief here. Indeed, it's user-friendly if we have an explanation to add actix-rt to dependencies at least.

Adding an explanation/instruction to add to dependencies would have eliminated my steps 1-4 for sure. My guess is I would not have opened this issue had that been the case. Personal views on what makes for a great tutorial aside, I think that's a strong candidate for "easiest plan to productively close the issue".

If taking my personal views into account, this explanation feels to me like might be introducing actix-rt in a way that abstracts it a bit too much. This would makes sense for some things (such as abstracting away the inner details of printf(3) when first learning C), but I'm not so sure actix-rt is so clear cut. As a 100% newbie, I might be left thinking "this is a new thing. It seems pretty important. It looks like I will have to deal with it in some detail. I need to know more than just 'add it to dependancies'". The effect on me would be to get distracted from the learning-task at hand (not always a bad thing).

Taking that into consideration, something like a link, comment-box, footnote, etc. to briefly explain the role actix-rt plays in the context of /docs/server content, and a promise to the reader that it's covered in later chapters. That way they can "learn only as much as they need to right now, but know where to go for something more in-depth". Without knowing much about actix or actix-rt, I can't comment on what would make a good balance when it comes to how much detail actix-rt needs when being introduced.

actix_rt::spawn also comes up a lot with those new to async. Many jump to tokio::spawn instead of using actix_rt, and spawning tasks doesn't seem to be covered anywhere in the docs. It might also be useful to re-export it under web::spawn similar to web::block.

I think this points to a broader issue with people assuming that actix-web "just uses tokio", and that all tokio runtime methods should "just work". !Send futures and the ability to use Rc instead of Arc, etc. is also relevant. A runtime section in the docs would probably help.

@ibraheemdev "just use tokio" is a path we are taking and more. Take a look at this PR and it's already ready. https://github.com/actix/actix-net/pull/266#issuecomment-808939487

I believe we should let user use whatever runtime they want as more as possible and not limiting them to a strict model. (This would not happen right away with a single PR but a general direction we would want to work on).

The problem about !Send is legit as it has not only to do with cost but also compiler issue. (Liking trying to use awc or actix inside tokio::spawn).

I guess the solution could be we mirror tokio when we can and try to support most tokio types/features when we can.

At the same time we want to keep the compat to already established actix-* eco. Documentation should be more specific on the part where a confustion may happen. (Like the awc example mentioned above).

There is a downside with this approach that would be the code base would be more complicated an could give trouble for future maintainers. But in general I believe the async Rust is heading towards a reduction of runtime fragmentation so the task would mostly be removing runtime related code and not adding more to it.

TLDR: we could make actix_rt stuff an opt-in like feature. It's there and if it's already used it's just like that. We encourage new comers to use whatever they like and only when they try to use actix-* crates in a specific way and/or after high perf/low overhead we guide them to use actix_rt(or counterpart of the same runtime feature of something like tokio, async_std)