From 7f0de705a39bf79d259eec82afe4d4902c7da4a4 Mon Sep 17 00:00:00 2001 From: memoryruins Date: Thu, 5 Apr 2018 20:55:19 -0400 Subject: [PATCH] Tweaks to Server chapter. --- guide/src/qs_3_5.md | 96 ++++++++++++++++++++++++--------------------- 1 file changed, 52 insertions(+), 44 deletions(-) diff --git a/guide/src/qs_3_5.md b/guide/src/qs_3_5.md index 274524024..65d8ed71f 100644 --- a/guide/src/qs_3_5.md +++ b/guide/src/qs_3_5.md @@ -1,13 +1,19 @@ # Server -The [*HttpServer*](../actix_web/struct.HttpServer.html) type is responsible for -serving http requests. *HttpServer* accepts application factory as a parameter, -Application factory must have `Send` + `Sync` boundaries. More about that in the -*multi-threading* section. To bind to a specific socket address, `bind()` must be used. -This method can be called multiple times. To start the http server, one of the *start* -methods can be used. `start()` method starts a simple server, `start_tls()` or `start_ssl()` -starts ssl server. *HttpServer* is an actix actor, it has to be initialized -within a properly configured actix system: +The [**HttpServer**](../actix_web/struct.HttpServer.html) type is responsible for +serving http requests. + +`HttpServer` accepts an application factory as a parameter, and the +application factory must have `Send` + `Sync` boundaries. More about that in the +*multi-threading* section. + +To bind to a specific socket address, `bind()` must be used, and it may be called multiple times. +To start the http server, one of the start methods. + +- use `start()` for a simple server +- use `start_tls()` or `start_ssl()` for a ssl server + +`HttpServer` is an actix actor. It must be initialized within a properly configured actix system: ```rust # extern crate actix; @@ -29,17 +35,17 @@ fn main() { } ``` -It is possible to start a server in a separate thread with the *spawn()* method. In that -case the server spawns a new thread and creates a new actix system in it. To stop -this server, send a `StopServer` message. +> It is possible to start a server in a separate thread with the `spawn()` method. In that +> case the server spawns a new thread and creates a new actix system in it. To stop +> this server, send a `StopServer` message. -Http server is implemented as an actix actor. It is possible to communicate with the server -via a messaging system. All start methods like `start()`, `start_ssl()`, etc. return the -address of the started http server. Actix http server accepts several messages: +`HttpServer` is implemented as an actix actor. It is possible to communicate with the server +via a messaging system. All start methods, e.g. `start()` and `start_ssl()`, return the +address of the started http server. It accepts several messages: -* `PauseServer` - Pause accepting incoming connections -* `ResumeServer` - Resume accepting incoming connections -* `StopServer` - Stop incoming connection processing, stop all workers and exit +- `PauseServer` - Pause accepting incoming connections +- `ResumeServer` - Resume accepting incoming connections +- `StopServer` - Stop incoming connection processing, stop all workers and exit ```rust # extern crate futures; @@ -74,7 +80,7 @@ fn main() { ## Multi-threading -Http server automatically starts an number of http workers, by default +`HttpServer` automatically starts an number of http workers, by default this number is equal to number of logical CPUs in the system. This number can be overridden with the `HttpServer::threads()` method. @@ -92,8 +98,10 @@ fn main() { ``` The server creates a separate application instance for each created worker. Application state -is not shared between threads, to share state `Arc` could be used. Application state -does not need to be `Send` and `Sync` but application factory must be `Send` + `Sync`. +is not shared between threads. To share state, `Arc` could be used. + +> Application state does not need to be `Send` and `Sync`, +> but factories must be `Send` + `Sync`. ## SSL @@ -123,22 +131,21 @@ fn main() { } ``` -Note on *HTTP/2.0* protocol over tls without prior knowledge, it requires -[tls alpn](https://tools.ietf.org/html/rfc7301). At the moment only -`openssl` has `alpn ` support. - -Please check [example](https://github.com/actix/actix-web/tree/master/examples/tls) -for a full example. +> **Note**: the *HTTP/2.0* protocol requires +> [tls alpn](https://tools.ietf.org/html/rfc7301). +> At the moment, only `openssl` has `alpn` support. +> For a full example, check out +> [examples/tls](https://github.com/actix/actix-web/tree/master/examples/tls). ## Keep-Alive -Actix can wait for requests on a keep-alive connection. *Keep alive* -connection behavior is defined by server settings. +Actix can wait for requests on a keep-alive connection. - * `75` or `Some(75)` or `KeepAlive::Timeout(75)` - enable 75 sec *keep alive* timer according - request and response settings. - * `None` or `KeepAlive::Disabled` - disable *keep alive*. - * `KeepAlive::Tcp(75)` - Use `SO_KEEPALIVE` socket option. +> *keep alive* connection behavior is defined by server settings. + +- `75`, `Some(75)`, `KeepAlive::Timeout(75)` - enable 75 second *keep alive* timer. +- `None` or `KeepAlive::Disabled` - disable *keep alive*. +- `KeepAlive::Tcp(75)` - use `SO_KEEPALIVE` socket option. ```rust # extern crate actix_web; @@ -163,11 +170,12 @@ fn main() { } ``` -If first option is selected then *keep alive* state is +If the first option is selected, then *keep alive* state is calculated based on the response's *connection-type*. By default -`HttpResponse::connection_type` is not defined in that case *keep alive* -defined by request's http version. Keep alive is off for *HTTP/1.0* -and is on for *HTTP/1.1* and *HTTP/2.0*. +`HttpResponse::connection_type` is not defined. In that case *keep alive* is +defined by the request's http version. + +> *keep alive* is **off** for *HTTP/1.0* and is **on** for *HTTP/1.1* and *HTTP/2.0*. *Connection type* can be change with `HttpResponseBuilder::connection_type()` method. @@ -186,19 +194,19 @@ fn index(req: HttpRequest) -> HttpResponse { ## Graceful shutdown -Actix http server supports graceful shutdown. After receiving a stop signal, workers -have a specific amount of time to finish serving requests. Workers still alive after the +`HttpServer` supports graceful shutdown. After receiving a stop signal, workers +have a specific amount of time to finish serving requests. Any workers still alive after the timeout are force-dropped. By default the shutdown timeout is set to 30 seconds. You can change this parameter with the `HttpServer::shutdown_timeout()` method. You can send a stop message to the server with the server address and specify if you want -graceful shutdown or not. The `start()` methods return address of the server. +graceful shutdown or not. The `start()` methods returns address of the server. -Http server handles several OS signals. *CTRL-C* is available on all OSs, +`HttpServer` handles several OS signals. *CTRL-C* is available on all OSs, other signals are available on unix systems. -* *SIGINT* - Force shutdown workers -* *SIGTERM* - Graceful shutdown workers -* *SIGQUIT* - Force shutdown workers +- *SIGINT* - Force shutdown workers +- *SIGTERM* - Graceful shutdown workers +- *SIGQUIT* - Force shutdown workers -It is possible to disable signal handling with `HttpServer::disable_signals()` method. +> It is possible to disable signal handling with `HttpServer::disable_signals()` method.