aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2013-01-18 19:51:00 +0100
committerLoïc Hoguin <[email protected]>2013-01-18 19:51:00 +0100
commita27296b34d3dc2481f0e3c013b7548690db26b01 (patch)
treea6d7540c1031ee6666d90d702f4a2525d45a030b
parent09c68ca755d685183c10d1a406844603e7bcf43b (diff)
downloadcowboy-a27296b34d3dc2481f0e3c013b7548690db26b01.tar.gz
cowboy-a27296b34d3dc2481f0e3c013b7548690db26b01.tar.bz2
cowboy-a27296b34d3dc2481f0e3c013b7548690db26b01.zip
Document loop handlers in the guide
-rw-r--r--guide/loop_handlers.md20
-rw-r--r--guide/toc.md1
2 files changed, 14 insertions, 7 deletions
diff --git a/guide/loop_handlers.md b/guide/loop_handlers.md
index 41f9e76..64cf80a 100644
--- a/guide/loop_handlers.md
+++ b/guide/loop_handlers.md
@@ -16,15 +16,23 @@ While the same can be accomplished using plain HTTP handlers,
it is recommended to use loop handlers because they are well-tested
and allow using built-in features like hibernation and timeouts.
-Callbacks
----------
-
-@todo Describe the callbacks.
-
Usage
-----
-@todo Explain how to use them.
+Loop handlers are used for requests where a response might not
+be immediately available, but where you would like to keep the
+connection open for a while in case the response arrives. The
+most known example of such practice is known as long-polling.
+
+Loop handlers can also be used for requests where a response is
+partially available and you need to stream the response body
+while the connection is open. The most known example of such
+practice is known as server-sent events.
+
+Loop handlers essentially wait for one or more Erlang messages
+and feed these messages to the `info/3` callback. It also features
+the `init/3` and `terminate/2` callbacks which work the same as
+for plain HTTP handlers.
The following handler waits for a message `{reply, Body}` before
sending a response. If this message doesn't arrive within 60
diff --git a/guide/toc.md b/guide/toc.md
index b6675e6..528f8c6 100644
--- a/guide/toc.md
+++ b/guide/toc.md
@@ -21,7 +21,6 @@ Cowboy User Guide
* Usage
* [Loop handlers](loop_handlers.md)
* Purpose
- * Callbacks
* Usage
* [Websocket handlers](ws_handlers.md)
* Purpose