From c807880f7ac73f813b2660ea81a00f7712a4e793 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Mon, 29 Aug 2016 12:39:49 +0200
Subject: Add old mailing list archives

---
 docs/en/cowboy/2.0/guide/handlers.asciidoc | 61 ++++++++++++++----------------
 1 file changed, 29 insertions(+), 32 deletions(-)

(limited to 'docs/en/cowboy/2.0/guide/handlers.asciidoc')

diff --git a/docs/en/cowboy/2.0/guide/handlers.asciidoc b/docs/en/cowboy/2.0/guide/handlers.asciidoc
index b6cefddc..a59b8cf6 100644
--- a/docs/en/cowboy/2.0/guide/handlers.asciidoc
+++ b/docs/en/cowboy/2.0/guide/handlers.asciidoc
@@ -9,42 +9,42 @@ The most basic handler in Cowboy implements the mandatory
 `init/2` callback, manipulates the request, optionally
 sends a response and then returns.
 
-This callback receives the xref:req[Req object] and the options
-defined during the xref:routing[router configuration].
+This callback receives the xref:req[Req object] and the initial
+state defined in the xref:routing[router configuration].
 
 A handler that does nothing would look like this:
 
 [source,erlang]
 ----
-init(Req, _Opts) ->
-    {ok, Req, #state{}}.
+init(Req, State) ->
+    {ok, Req, State}.
 ----
 
-Despite sending no reply, a `204 No Content` reply will be
-sent to the client, as Cowboy makes sure that a reply is
+Despite sending no reply, a `204 No Content` response will be
+sent to the client, as Cowboy makes sure that a response is
 sent for every request.
 
-We need to use the Req object for sending a reply.
+We need to use the Req object to reply.
 
 [source,erlang]
 ----
-init(Req, _Opts) ->
-    Req2 = cowboy_req:reply(200, [
+init(Req0, State) ->
+    Req = cowboy_req:reply(200, [
         {<<"content-type">>, <<"text/plain">>}
-    ], <<"Hello World!">>, Req),
-    {ok, Req2, #state{}}.
+    ], <<"Hello World!">>, Req0),
+    {ok, Req, State}.
 ----
 
-As you can see we return a 3-tuple. `ok` means that the
-handler ran successfully. The Req object is returned as
-it may have been modified as is the case here: replying
-returns a modified Req object that you need to return
-back to Cowboy for proper operations.
+Cowboy will immediately send a response when `cowboy:reply/4`
+is called.
+
+We then return a 3-tuple. `ok` means that the handler ran
+successfully. We also give the modified Req back to Cowboy.
 
 The last value of the tuple is a state that will be used
 in every subsequent callbacks to this handler. Plain HTTP
 handlers only have one additional callback, the optional
-`terminate/3`.
+and rarely used `terminate/3`.
 
 === Other handlers
 
@@ -64,16 +64,16 @@ following snippet switches to a Websocket handler:
 
 [source,erlang]
 ----
-init(Req, _Opts) ->
-	{cowboy_websocket, Req, #state{}}.
+init(Req, State) ->
+	{cowboy_websocket, Req, State}.
 ----
 
 You can also switch to your own custom handler type:
 
 [source,erlang]
 ----
-init(Req, _Opts) ->
-	{my_handler_type, Req, #state{}}.
+init(Req, State) ->
+	{my_handler_type, Req, State}.
 ----
 
 How to implement a custom handler type is described in the
@@ -81,12 +81,12 @@ xref:sub_protocols[Sub protocols] chapter.
 
 === Cleaning up
 
-All handlers coming with Cowboy allow the use of the optional
-`terminate/3` callback.
+With the exception of Websocket handlers, all handler types
+provide the optional `terminate/3` callback.
 
 [source,erlang]
 ----
-terminate(_Reason, Req, State) ->
+terminate(_Reason, _Req, _State) ->
     ok.
 ----
 
@@ -94,12 +94,9 @@ This callback is strictly reserved for any required cleanup.
 You cannot send a response from this function. There is no
 other return value.
 
-If you used the process dictionary, timers, monitors or may
-be receiving messages, then you can use this function to clean
-them up, as Cowboy might reuse the process for the next
-keep-alive request.
+This callback is optional because it is rarely necessary.
+Cleanup should be done in separate processes directly (by
+monitoring the handler process to detect when it exits).
 
-Note that while this function may be called in a Websocket
-handler, it is generally not useful to do any clean up as
-the process terminates immediately after calling this callback
-when using Websocket.
+Cowboy does not reuse processes for different requests. The
+process will terminate soon after this call returns.
-- 
cgit v1.2.3