From 074d18209da71f0bb0f5b348e3ab26a4e80e1924 Mon Sep 17 00:00:00 2001 From: Rob Ede Date: Tue, 8 Feb 2022 10:21:47 +0000 Subject: [PATCH] better document relationship with tokio --- actix-web-codegen/src/lib.rs | 4 +++ actix-web/README.md | 2 +- actix-web/src/handler.rs | 6 +++- actix-web/src/lib.rs | 41 +++++++++++++------------ actix-web/src/rt.rs | 59 ++++++++++++++++++++++++++++-------- 5 files changed, 78 insertions(+), 34 deletions(-) diff --git a/actix-web-codegen/src/lib.rs b/actix-web-codegen/src/lib.rs index f41e1ce38..5ca5616b6 100644 --- a/actix-web-codegen/src/lib.rs +++ b/actix-web-codegen/src/lib.rs @@ -152,6 +152,10 @@ method_macro!(Patch, patch); /// Marks async main function as the Actix Web system entry-point. /// +/// Note that Actix Web also works under `#[tokio::main]` since version 4.0. However, this macro is +/// still necessary for actor support (since actors use a `System`). Read more in the +/// [`actix_web::rt`](https://docs.rs/actix-web/4/actix_web/rt) module docs. +/// /// # Examples /// ``` /// #[actix_web::main] diff --git a/actix-web/README.md b/actix-web/README.md index 2a87d340d..4adeb3910 100644 --- a/actix-web/README.md +++ b/actix-web/README.md @@ -32,7 +32,7 @@ - Static assets - SSL support using OpenSSL or Rustls - Middlewares ([Logger, Session, CORS, etc](https://actix.rs/docs/middleware/)) -- Includes an async [HTTP client](https://docs.rs/awc/) +- Integrates with the [`awc` HTTP client](https://docs.rs/awc/) - Runs on stable Rust 1.54+ ## Documentation diff --git a/actix-web/src/handler.rs b/actix-web/src/handler.rs index 7eb70ed25..cf86cb38b 100644 --- a/actix-web/src/handler.rs +++ b/actix-web/src/handler.rs @@ -10,12 +10,16 @@ use crate::{ /// The interface for request handlers. /// /// # What Is A Request Handler -/// A request handler has three requirements: +/// In short, a handler is just an async function that receives request-based arguments, in any +/// order, and returns something that can be converted to a response. +/// +/// In particular, a request handler has three requirements: /// 1. It is an async function (or a function/closure that returns an appropriate future); /// 1. The function parameters (up to 12) implement [`FromRequest`]; /// 1. The async function (or future) resolves to a type that can be converted into an /// [`HttpResponse`] (i.e., it implements the [`Responder`] trait). /// +/// /// # Compiler Errors /// If you get the error `the trait Handler<_> is not implemented`, then your handler does not /// fulfill the _first_ of the above requirements. Missing other requirements manifest as errors on diff --git a/actix-web/src/lib.rs b/actix-web/src/lib.rs index c3313db81..34bee7529 100644 --- a/actix-web/src/lib.rs +++ b/actix-web/src/lib.rs @@ -42,28 +42,29 @@ //! and otherwise utilizing them. //! //! # Features -//! * Supports *HTTP/1.x* and *HTTP/2* -//! * Streaming and pipelining -//! * Keep-alive and slow requests handling -//! * Client/server [WebSockets](https://actix.rs/docs/websockets/) support -//! * Transparent content compression/decompression (br, gzip, deflate, zstd) -//! * Powerful [request routing](https://actix.rs/docs/url-dispatch/) -//! * Multipart streams -//! * Static assets -//! * SSL support using OpenSSL or Rustls -//! * Middlewares ([Logger, Session, CORS, etc](https://actix.rs/docs/middleware/)) -//! * Includes an async [HTTP client](https://docs.rs/awc/) -//! * Runs on stable Rust 1.54+ +//! - Supports HTTP/1.x and HTTP/2 +//! - Streaming and pipelining +//! - Powerful [request routing](https://actix.rs/docs/url-dispatch/) with optional macros +//! - Full [Tokio](https://tokio.rs) compatibility +//! - Keep-alive and slow requests handling +//! - Client/server [WebSockets](https://actix.rs/docs/websockets/) support +//! - Transparent content compression/decompression (br, gzip, deflate, zstd) +//! - Multipart streams +//! - Static assets +//! - SSL support using OpenSSL or Rustls +//! - Middlewares ([Logger, Session, CORS, etc](middleware)) +//! - Integrates with the [`awc` HTTP client](https://docs.rs/awc/) +//! - Runs on stable Rust 1.54+ //! //! # Crate Features -//! * `cookies` - cookies support (enabled by default) -//! * `macros` - routing and runtime macros (enabled by default) -//! * `compress-brotli` - brotli content encoding compression support (enabled by default) -//! * `compress-gzip` - gzip and deflate content encoding compression support (enabled by default) -//! * `compress-zstd` - zstd content encoding compression support (enabled by default) -//! * `openssl` - HTTPS support via `openssl` crate, supports `HTTP/2` -//! * `rustls` - HTTPS support via `rustls` crate, supports `HTTP/2` -//! * `secure-cookies` - secure cookies support +//! - `cookies` - cookies support (enabled by default) +//! - `macros` - routing and runtime macros (enabled by default) +//! - `compress-brotli` - brotli content encoding compression support (enabled by default) +//! - `compress-gzip` - gzip and deflate content encoding compression support (enabled by default) +//! - `compress-zstd` - zstd content encoding compression support (enabled by default) +//! - `openssl` - HTTPS support via `openssl` crate, supports `HTTP/2` +//! - `rustls` - HTTPS support via `rustls` crate, supports `HTTP/2` +//! - `secure-cookies` - secure cookies support #![deny(rust_2018_idioms, nonstandard_style)] #![warn(future_incompatible)] diff --git a/actix-web/src/rt.rs b/actix-web/src/rt.rs index efe9fdfe6..3b4f21b46 100644 --- a/actix-web/src/rt.rs +++ b/actix-web/src/rt.rs @@ -1,9 +1,10 @@ -//! A selection of re-exports from [`actix-rt`] and [`tokio`]. +//! A selection of re-exports from [`tokio`] and [`actix-rt`]. //! -//! [`actix-rt`]: https://docs.rs/actix_rt -//! [`tokio`]: https://docs.rs/tokio +//! Actix Web runs on [Tokio], providing full[^compat] compatibility with its huge ecosystem of +//! crates. Each of the server's workers uses a single-threaded runtime. Read more about the +//! architecture in [`actix-rt`]'s docs. //! -//! # Running Actix Web Macro-less +//! # Running Actix Web Without Macros //! ```no_run //! use actix_web::{middleware, rt, web, App, HttpRequest, HttpServer}; //! @@ -12,19 +13,53 @@ //! "Hello world!\r\n" //! } //! -//! # fn main() -> std::io::Result<()> { -//! rt::System::new().block_on( +//! fn main() -> std::io::Result<()> { +//! rt::System::new().block_on( +//! HttpServer::new(|| { +//! App::new().service(web::resource("/").route(web::get().to(index))) +//! }) +//! .bind(("127.0.0.1", 8080))? +//! .run() +//! ) +//! } +//! ``` +//! +//! # Running Actix Web Using `#[tokio::main]` +//! If you need to run something alongside Actix Web that uses Tokio's work stealing functionality, +//! you can run Actix Web under `#[tokio::main]`. The [`Server`](crate::dev::Server) object returned +//! from [`HttpServer::run`](crate::HttpServer::run) can also be [`spawn`]ed, if preferred. +//! +//! Note that `actix` actor support (and therefore WebSocket support through `actix-web-actors`) +//! still require `#[actix_web::main]` since they require a [`System`] to be set up. +//! +//! ```no_run +//! use actix_web::{get, middleware, rt, web, App, HttpRequest, HttpServer}; +//! +//! #[get("/")] +//! async fn index(req: HttpRequest) -> &'static str { +//! println!("REQ: {:?}", req); +//! "Hello world!\r\n" +//! } +//! +//! #[tokio::main] +//! async fn main() -> std::io::Result<()> { //! HttpServer::new(|| { -//! App::new() -//! .wrap(middleware::Logger::default()) -//! .service(web::resource("/").route(web::get().to(index))) +//! App::new().service(index) //! }) //! .bind(("127.0.0.1", 8080))? -//! .workers(1) //! .run() -//! ) -//! # } +//! .await +//! } //! ``` +//! +//! [^compat]: Crates that use Tokio's [`block_in_place`] will not work with Actix Web. Fortunately, +//! the vast majority of Tokio-based crates do not use it. +//! +//! [`actix-rt`]: https://docs.rs/actix_rt +//! [`tokio`]: https://docs.rs/tokio +//! [Tokio]: https://docs.rs/tokio +//! [`spawn`]: https://docs.rs/tokio/1/tokio/fn.spawn.html +//! [`block_in_place`]: https://docs.rs/tokio/1/tokio/task/fn.block_in_place.html // In particular: // - Omit the `Arbiter` types because they have limited value here.