From c2ad65a61dc498d46a4b417891e885b17b51f9a4 Mon Sep 17 00:00:00 2001 From: memoryruins Date: Thu, 5 Apr 2018 19:43:17 -0400 Subject: [PATCH] Various tweaks to Application chapter. --- guide/src/qs_3.md | 55 ++++++++++++++++++++++++----------------------- 1 file changed, 28 insertions(+), 27 deletions(-) diff --git a/guide/src/qs_3.md b/guide/src/qs_3.md index bcfdee8ad..32cd6bfb4 100644 --- a/guide/src/qs_3.md +++ b/guide/src/qs_3.md @@ -1,20 +1,21 @@ # Application -Actix web provides some primitives to build web servers and applications with Rust. -It provides routing, middlewares, pre-processing of requests, and post-processing of responses, +Actix web provides various primitives to build web servers and applications with Rust. +It provides routing, middlewares, pre-processing of requests, post-processing of responses, websocket protocol handling, multipart streams, etc. All actix web servers are built around the `App` instance. -It is used for registering routes for resources, and middlewares. -It also stores application specific state that is shared across all handlers -within same application. +It is used for registering routes for resources and middlewares. +It also stores application state shared across all handlers within same application. -Application acts as a namespace for all routes, i.e all routes for a specific application +Applications act as a namespace for all routes, i.e all routes for a specific application have the same url path prefix. The application prefix always contains a leading "/" slash. -If supplied prefix does not contain leading slash, it gets inserted. -The prefix should consist of value path segments. i.e for an application with prefix `/app` -any request with the paths `/app`, `/app/` or `/app/test` would match, -but path `/application` would not match. +If a supplied prefix does not contain leading slash, it is automatically inserted. +The prefix should consist of value path segments. + +> For an application with prefix `/app`, +> any request with the paths `/app`, `/app/`, or `/app/test` would match; +> however, the path `/application` would not match. ```rust,ignore # extern crate actix_web; @@ -31,10 +32,11 @@ but path `/application` would not match. # } ``` -In this example application with `/app` prefix and `index.html` resource -gets created. This resource is available as on `/app/index.html` url. -For more information check -[*URL Matching*](./qs_5.html#using-a-application-prefix-to-compose-applications) section. +In this example, an application with the `/app` prefix and a `index.html` resource +are created. This resource is available through the `/app/index.html` url. + +> For more information, check the +> [URL Dispatch](./qs_5.html#using-a-application-prefix-to-compose-applications) section. Multiple applications can be served with one server: @@ -59,18 +61,17 @@ fn main() { } ``` -All `/app1` requests route to the first application, `/app2` to the second and then all other to the third. -Applications get matched based on registration order, if an application with more general -prefix is registered before a less generic one, that would effectively block the less generic -application from getting matched. For example, if *application* with prefix "/" gets registered -as first application, it would match all incoming requests. +All `/app1` requests route to the first application, `/app2` to the second, and all other to the third. +**Applications get matched based on registration order**. If an application with a more generic +prefix is registered before a less generic one, it would effectively block the less generic +application matching. For example, if an `App` with the prefix `"/"` was registered +as the first application, it would match all incoming requests. ## State Application state is shared with all routes and resources within the same application. -State can be accessed with the `HttpRequest::state()` method as a read-only, -but an interior mutability pattern with `RefCell` can be used to achieve state mutability. -State can be accessed with `HttpContext::state()` when using an http actor. +When using an http actor,state can be accessed with the `HttpRequest::state()` as read-only, +but interior mutability with `RefCell` can be used to achieve state mutability. State is also available for route matching predicates and middlewares. Let's write a simple application that uses shared state. We are going to store request count @@ -102,8 +103,8 @@ fn main() { } ``` -Note on application state, http server accepts an application factory rather than an application -instance. Http server constructs an application instance for each thread, so application state -must be constructed multiple times. If you want to share state between different threads, a -shared object should be used, like `Arc`. Application state does not need to be `Send` and `Sync` -but the application factory must be `Send` + `Sync`. +> **Note**: http server accepts an application factory rather than an application +> instance. Http server constructs an application instance for each thread, thus application state +> must be constructed multiple times. If you want to share state between different threads, a +> shared object should be used, e.g. `Arc`. Application state does not need to be `Send` and `Sync`, +> but the application factory must be `Send` + `Sync`.