mirrors/actix-web
1
0
Fork 0
mirror of https://github.com/actix/actix-web.git synced 2024-10-21 09:23:54 +00:00
Code Issues Projects Releases Wiki Activity

Tweaks to Server chapter.

Browse source
This commit is contained in:
memoryruins 2018-04-05 20:55:19 -04:00
parent c2ad65a61d
commit 7f0de705a3
1 changed files with 52 additions and 44 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

96
guide/src/qs_3_5.md
View file

@ -1,13 +1,19 @@
# Server # Server
The [*HttpServer*](../actix_web/struct.HttpServer.html) type is responsible for The [**HttpServer**](../actix_web/struct.HttpServer.html) type is responsible for
serving http requests. *HttpServer* accepts application factory as a parameter, serving http requests.
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. `HttpServer` accepts an application factory as a parameter, and the
This method can be called multiple times. To start the http server, one of the *start* application factory must have `Send` + `Sync` boundaries. More about that in the
methods can be used. `start()` method starts a simple server, `start_tls()` or `start_ssl()` *multi-threading* section.
starts ssl server. *HttpServer* is an actix actor, it has to be initialized
within a properly configured actix system: 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 ```rust
# extern crate actix; # 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 > 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 > case the server spawns a new thread and creates a new actix system in it. To stop
this server, send a `StopServer` message. > this server, send a `StopServer` message.
Http server is implemented as an actix actor. It is possible to communicate with the server `HttpServer` 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 via a messaging system. All start methods, e.g. `start()` and `start_ssl()`, return the
address of the started http server. Actix http server accepts several messages: address of the started http server. It accepts several messages:
* `PauseServer` - Pause accepting incoming connections - `PauseServer` - Pause accepting incoming connections
* `ResumeServer` - Resume accepting incoming connections - `ResumeServer` - Resume accepting incoming connections
* `StopServer` - Stop incoming connection processing, stop all workers and exit - `StopServer` - Stop incoming connection processing, stop all workers and exit
```rust ```rust
# extern crate futures; # extern crate futures;
@ -74,7 +80,7 @@ fn main() {
## Multi-threading ## 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 this number is equal to number of logical CPUs in the system. This number
can be overridden with the `HttpServer::threads()` method. 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 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 is not shared between threads. To share state, `Arc` could be used.
does not need to be `Send` and `Sync` but application factory must be `Send` + `Sync`.
> Application state does not need to be `Send` and `Sync`,
> but factories must be `Send` + `Sync`.
## SSL ## SSL
@ -123,22 +131,21 @@ fn main() {
} }
``` ```
Note on *HTTP/2.0* protocol over tls without prior knowledge, it requires > **Note**: the *HTTP/2.0* protocol requires
[tls alpn](https://tools.ietf.org/html/rfc7301). At the moment only > [tls alpn](https://tools.ietf.org/html/rfc7301).
`openssl` has `alpn ` support. > At the moment, only `openssl` has `alpn` support.
> For a full example, check out
Please check [example](https://github.com/actix/actix-web/tree/master/examples/tls) > [examples/tls](https://github.com/actix/actix-web/tree/master/examples/tls).
for a full example.
## Keep-Alive ## Keep-Alive
Actix can wait for requests on a keep-alive connection. *Keep alive* Actix can wait for requests on a keep-alive connection.
connection behavior is defined by server settings.
* `75` or `Some(75)` or `KeepAlive::Timeout(75)` - enable 75 sec *keep alive* timer according > *keep alive* connection behavior is defined by server settings.
request and response settings.
* `None` or `KeepAlive::Disabled` - disable *keep alive*. - `75`, `Some(75)`, `KeepAlive::Timeout(75)` - enable 75 second *keep alive* timer.
* `KeepAlive::Tcp(75)` - Use `SO_KEEPALIVE` socket option. - `None` or `KeepAlive::Disabled` - disable *keep alive*.
- `KeepAlive::Tcp(75)` - use `SO_KEEPALIVE` socket option.
```rust ```rust
# extern crate actix_web; # 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 calculated based on the response's *connection-type*. By default
`HttpResponse::connection_type` is not defined in that case *keep alive* `HttpResponse::connection_type` is not defined. In that case *keep alive* is
defined by request's http version. Keep alive is off for *HTTP/1.0* defined by the request's http version.
and is on for *HTTP/1.1* and *HTTP/2.0*.
> *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. *Connection type* can be change with `HttpResponseBuilder::connection_type()` method.
@ -186,19 +194,19 @@ fn index(req: HttpRequest) -> HttpResponse {
## Graceful shutdown ## Graceful shutdown
Actix http server supports graceful shutdown. After receiving a stop signal, workers `HttpServer` supports graceful shutdown. After receiving a stop signal, workers
have a specific amount of time to finish serving requests. Workers still alive after the 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. 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 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 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. other signals are available on unix systems.
* *SIGINT* - Force shutdown workers - *SIGINT* - Force shutdown workers
* *SIGTERM* - Graceful shutdown workers - *SIGTERM* - Graceful shutdown workers
* *SIGQUIT* - Force 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.