Document body reading in auto mode

It is now tested both via cowboy_req:read_body and
via cowboy_req:cast.

Removes a bad example from the guide of body reading
with period of infinity, which does not work.

1 files changed, 23 insertions, 7 deletions

diff --git a/doc/src/guide/req_body.asciidoc b/doc/src/guide/req_body.asciidoc
index 4906811..88389f6 100644
--- a/doc/src/guide/req_body.asciidoc
+++ b/doc/src/guide/req_body.asciidoc
@@ -74,17 +74,33 @@ only up to 1MB for up to 5 seconds:
     #{length => 1000000, period => 5000}).
 ----
 
-You may also disable the length limit:
+These two options can effectively be used to control
+the rate of transmission of the request body.
+
+It is also possible to asynchronously read the request
+body using auto mode:
 
 [source,erlang]
-{ok, Data, Req} = cowboy_req:read_body(Req0, #{length => infinity}).
+----
+Ref = make_ref(),
+cowboy_req:cast({read_body, self(), Ref, auto, infinity}, Req).
+----
 
-This makes the function wait 15 seconds and return with
-whatever arrived during that period. This is not
-recommended for public facing applications.
+Cowboy will wait indefinitely for data and then send a
+`request_body` message as soon as it has data available,
+regardless of length.
 
-These two options can effectively be used to control
-the rate of transmission of the request body.
+[source,erlang]
+----
+receive
+    {request_body, Ref, nofin, Data} ->
+        do_something(Data);
+    {request_body, Ref, fin, _BodyLen, Data} ->
+        do_something(Data)
+end.
+----
+
+Asynchronous reading of data pairs well with loop handlers.
 
 === Streaming the body