From 5e17a846af5ed1a044f5f1e4489d017e5390f506 Mon Sep 17 00:00:00 2001
From: Nikolay Kim <fafhrd91@gmail.com>
Date: Tue, 26 Dec 2017 11:19:08 -0800
Subject: [PATCH] add notes on sync primitives

---
 guide/src/qs_4.md | 11 ++++++++---
 guide/src/qs_7.md |  5 +++--
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/guide/src/qs_4.md b/guide/src/qs_4.md
index b96d64bff..e44483d07 100644
--- a/guide/src/qs_4.md
+++ b/guide/src/qs_4.md
@@ -1,7 +1,7 @@
 # Handler
 
-A request handler can by any object that implements
-[`Handler` trait](../actix_web/dev/trait.Handler.html#implementors).
+A request handler can by any object that implements 
+[*Handler trait*](../actix_web/dev/trait.Handler.html).
 Request handling happen in two stages. First handler object get called. 
 Handle can return any object that implements 
 [*Responder trait*](../actix_web/trait.Responder.html#foreign-impls).
@@ -11,7 +11,7 @@ result of the `respond_to()` call get converted to `Reply` object.
 By default actix provides `Responder` implementations for some standard types, 
 like `&'static str`, `String`, etc.
 For complete list of implementations check 
-[Responder documentation](../actix_web/trait.Responder.html#foreign-impls).
+[*Responder documentation*](../actix_web/trait.Responder.html#foreign-impls).
 
 Examples of valid handlers:
 
@@ -115,6 +115,11 @@ fn main() {
 }
 ```
 
+Be careful with synchronization primitives like *Mutex* or *RwLock*. Actix web framework
+handles request asynchronously, by blocking thread execution all concurrent
+request handling processes would block. If you need to share or update some state 
+from multiple threads consider using [actix](https://actix.github.io/actix/actix/)  actor system.
+
 ## Response with custom type
 
 To return custom type directly from handler function type needs to implement `Responder` trait.
diff --git a/guide/src/qs_7.md b/guide/src/qs_7.md
index a51c5c8a6..f4fdf5e97 100644
--- a/guide/src/qs_7.md
+++ b/guide/src/qs_7.md
@@ -6,8 +6,9 @@ Builder-like patter is used to construct an instance of `HttpResponse`.
 `HttpResponse` provides several method that returns `HttpResponseBuilder` instance,
 which is implements various convinience methods that helps build response.
 Check [documentation](../actix_web/dev/struct.HttpResponseBuilder.html)
-for type description. Methods `.body`, `.finish`, `.json` finalizes response creation,
-if this methods get call for the same builder instance, builder will panic.
+for type description. Methods `.body`, `.finish`, `.json` finalizes response creation and
+returns constructed *HttpResponse* instance. if this methods get called for the same
+builder instance multiple times, builder will panic.
 
 ```rust
 # extern crate actix_web;