diff options
author | Loïc Hoguin <[email protected]> | 2016-08-29 12:39:49 +0200 |
---|---|---|
committer | Loïc Hoguin <[email protected]> | 2016-08-29 12:40:03 +0200 |
commit | c807880f7ac73f813b2660ea81a00f7712a4e793 (patch) | |
tree | ba1d09e9b177f230665a80513b33fbd532000ce4 /docs/en/cowboy/2.0/guide/handlers.asciidoc | |
parent | b1df25a7d9cda697513650659b781b55b40898f8 (diff) | |
download | ninenines.eu-c807880f7ac73f813b2660ea81a00f7712a4e793.tar.gz ninenines.eu-c807880f7ac73f813b2660ea81a00f7712a4e793.tar.bz2 ninenines.eu-c807880f7ac73f813b2660ea81a00f7712a4e793.zip |
Add old mailing list archives
Diffstat (limited to 'docs/en/cowboy/2.0/guide/handlers.asciidoc')
-rw-r--r-- | docs/en/cowboy/2.0/guide/handlers.asciidoc | 61 |
1 files changed, 29 insertions, 32 deletions
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. |