diff --git a/actix-web/src/server.rs b/actix-web/src/server.rs index e92985d39..2cc00cb9f 100644 --- a/actix-web/src/server.rs +++ b/actix-web/src/server.rs @@ -99,6 +99,12 @@ where B: MessageBody + 'static, { /// Create new HTTP server with application factory + /// + /// # Worker Count + /// + /// The `factory` will be instantiated multiple times in most configurations. See + /// [`bind()`](Self::bind()) docs for more on how worker count and bind address resolution + /// causes multiple server factory instantiations. pub fn new(factory: F) -> Self { HttpServer { factory, @@ -119,7 +125,18 @@ where /// Sets number of workers to start (per bind address). /// - /// By default, the number of available physical CPUs is used as the worker count. + /// The default worker count is the determined by [`std::thread::available_parallelism()`]. See + /// its documentation to determine what behavior you should expect when server is run. + /// + /// Note that the server factory passed to [`new`](Self::new()) will be instantiated **at least + /// once per worker**. See [`bind()`](Self::bind()) docs for more on how worker count and bind + /// address resolution causes multiple server factory instantiations. + /// + /// `num` must be greater than 0. + /// + /// # Panics + /// + /// Panics if `num` is 0. pub fn workers(mut self, num: usize) -> Self { self.builder = self.builder.workers(num); self @@ -319,23 +336,41 @@ where /// Resolves socket address(es) and binds server to created listener(s). /// /// # Hostname Resolution - /// When `addr` includes a hostname, it is possible for this method to bind to both the IPv4 and - /// IPv6 addresses that result from a DNS lookup. You can test this by passing `localhost:8080` - /// and noting that the server binds to `127.0.0.1:8080` _and_ `[::1]:8080`. To bind additional - /// addresses, call this method multiple times. + /// + /// When `addrs` includes a hostname, it is possible for this method to bind to both the IPv4 + /// and IPv6 addresses that result from a DNS lookup. You can test this by passing + /// `localhost:8080` and noting that the server binds to `127.0.0.1:8080` _and_ `[::1]:8080`. To + /// bind additional addresses, call this method multiple times. /// /// Note that, if a DNS lookup is required, resolving hostnames is a blocking operation. /// + /// # Worker Count + /// + /// The `factory` will be instantiated multiple times in most scenarios. The number of + /// instantiations is number of [`workers`](Self::workers()) × number of sockets resolved by + /// `addrs`. + /// + /// For example, if you've manually set [`workers`](Self::workers()) to 2, and use `127.0.0.1` + /// as the bind `addrs`, then `factory` will be instantiated twice. However, using `localhost` + /// as the bind `addrs` can often resolve to both `127.0.0.1` (IPv4) _and_ `::1` (IPv6), causing + /// the `factory` to be instantiated 4 times (2 workers × 2 bind addresses). + /// + /// Using a bind address of `0.0.0.0`, which signals to use all interfaces, may also multiple + /// the number of instantiations in a similar way. + /// /// # Typical Usage + /// /// In general, use `127.0.0.1:` when testing locally and `0.0.0.0:` when deploying /// (with or without a reverse proxy or load balancer) so that the server is accessible. /// /// # Errors + /// /// Returns an `io::Error` if: /// - `addrs` cannot be resolved into one or more socket addresses; /// - all the resolved socket addresses are already bound. /// /// # Example + /// /// ``` /// # use actix_web::{App, HttpServer}; /// # fn inner() -> std::io::Result<()> { @@ -356,6 +391,8 @@ where /// Resolves socket address(es) and binds server to created listener(s) for plaintext HTTP/1.x /// or HTTP/2 connections. + /// + /// See [`bind()`](Self::bind()) for more details on `addrs` argument. #[cfg(feature = "http2")] pub fn bind_auto_h2c(mut self, addrs: A) -> io::Result { let sockets = bind_addrs(addrs, self.backlog)?; @@ -370,7 +407,7 @@ where /// Resolves socket address(es) and binds server to created listener(s) for TLS connections /// using Rustls v0.20. /// - /// See [`bind()`](Self::bind) for more details on `addrs` argument. + /// See [`bind()`](Self::bind()) for more details on `addrs` argument. /// /// ALPN protocols "h2" and "http/1.1" are added to any configured ones. #[cfg(feature = "rustls-0_20")] @@ -389,7 +426,7 @@ where /// Resolves socket address(es) and binds server to created listener(s) for TLS connections /// using Rustls v0.21. /// - /// See [`bind()`](Self::bind) for more details on `addrs` argument. + /// See [`bind()`](Self::bind()) for more details on `addrs` argument. /// /// ALPN protocols "h2" and "http/1.1" are added to any configured ones. #[cfg(feature = "rustls-0_21")] @@ -408,7 +445,7 @@ where /// Resolves socket address(es) and binds server to created listener(s) for TLS connections /// using OpenSSL. /// - /// See [`bind()`](Self::bind) for more details on `addrs` argument. + /// See [`bind()`](Self::bind()) for more details on `addrs` argument. /// /// ALPN protocols "h2" and "http/1.1" are added to any configured ones. #[cfg(feature = "openssl")]