From b09f3a570d702be7a55c36e5f5b4b63b26198637 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Thu, 23 Jan 2014 15:54:20 +0100
Subject: Clarify what stream_body is doing
---
manual/cowboy_req.md | 17 +++++++++++------
1 file changed, 11 insertions(+), 6 deletions(-)
diff --git a/manual/cowboy_req.md b/manual/cowboy_req.md
index d7af41f..1d3841d 100644
--- a/manual/cowboy_req.md
+++ b/manual/cowboy_req.md
@@ -419,26 +419,31 @@ Request body related exports
> read before.
### stream_body(Req) -> stream_body(1000000, Req)
-### stream_body(MaxSegmentSize, Req) -> {ok, Data, Req2}
+### stream_body(MaxReadSize, Req) -> {ok, Data, Req2}
| {done, Req2} | {error, Reason}
> Types:
-> * MaxSegmentSize = non_neg_integer()
+> * MaxReadSize = non_neg_integer()
> * Data = binary()
> * Reason = atom()
>
> Stream the request body.
>
-> This function will return a segment of the request body
-> with a size of up to `MaxSegmentSize`, or 1MB by default.
-> This function can be called repeatedly until a `done` tuple
-> is returned, indicating the body has been fully received.
+> This function will return the next segment of the body.
>
> Cowboy will properly handle chunked transfer-encoding by
> default. If any other transfer-encoding or content-encoding
> has been used for the request, custom decoding functions
> can be used. They must be specified using `init_stream/4`.
>
+> The amount of data returned by this function may vary
+> depending on the current state of the request. If data
+> is already available in the buffer then it is used fully,
+> otherwise Cowboy will read up to `MaxReadSize` bytes from
+> the socket. By default Cowboy will read up to 1MB of data.
+> It is then decoded, which may grow or shrink it, depending
+> on the encoding headers, before it is finally returned.
+>
> After the body has been streamed fully, Cowboy will remove
> the transfer-encoding header from the `Req` object, and add
> the content-length header if it wasn't already there.
--
cgit v1.2.3