docs: improve HttpServer docs on worker / bind relationship wrt factory instantiations

Author: robjtede

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:<port>` when testing locally and `0.0.0.0:<port>` 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<A: net::ToSocketAddrs>(mut self, addrs: A) -> io::Result<Self> {
         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")]