Anonymous avatar Anonymous committed 07092da

initial description of streamed bodies

Comments (0)

Files changed (2)

 * [[WebmachineReqData]]
 * [[WebmachineDebugging]]
 * [[WebmachineReftrans]]
+* [[StreamBody]]
 
+== Webmachine Streamed Bodies ==
+
+Webmachine allows the resource developer to handle request and response bodies as either whole units (binary or iolist) to be handed around at once, or else to choose to "stream" the body.
+
+The body-handling functions are:
+
+* {{{ wrq:req_body/1 }}}
+* {{{ wrq:stream_req_body/2 }}}
+* {{{ wrq:set_resp_body/2 }}}
+
+The first of these ({{{ wrq:req_body/1 }}}) is the simplest.  It will provide the whole incoming request body as a binary.  (Unless the body is too large, as set by {{{ wrq:set_max_recv_body/2 }}} or defaulting to 50M)  For the majority of resources, this is the easiest way to handle the incoming request body.
+
+If a resource instead wants to handle the incoming request body a hunk at a time, it may call {{{ wrq:stream_req_body/2 }}} instead.  Instead of a binary, this produces a {{{ StreamBody }}} structure.
+
+(It is an error to call both {{{ wrq:req_body/1 }}} and {{{ wrq:stream_req_body/2 }}} in the execution of a single resource.)
+
+A {{{ StreamBody }}} is a pair of the form {{{ {Data,Next} }}} where {{{ Data }}} is a binary and {{{ Next }}} is either the atom {{{ done }}} signifying the end of the body or else a 0-arity function that, when called, will produce the "next" {{{ StreamBody }}} structure.  
+
+The integer parameter to {{{ wrq:stream_req_body/2 }}} indicates the maximum size in bytes of any {{{ Hunk }}} from the resulting {{{ StreamBody }}}.
+
+When a resource provides a body to be sent in the response, it should use {{{ wrq:set_resp_body/2 }}}.  The parameter to this function may be either an iolist, representing the entire body, or else a pair of the form {{{ {stream, StreamBody} }}}.
+
+
+
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.