diff options
Diffstat (limited to 'guide')
| -rw-r--r-- | guide/http_handlers.md | 23 | ||||
| -rw-r--r-- | guide/introduction.md | 6 |
2 files changed, 20 insertions, 9 deletions
diff --git a/guide/http_handlers.md b/guide/http_handlers.md index aba0e06..f3ac185 100644 --- a/guide/http_handlers.md +++ b/guide/http_handlers.md @@ -10,17 +10,26 @@ Usage ----- You need to implement three callbacks for HTTP handlers. The first, -`init/3`, is common to all handlers. In the context of HTTP handlers -this should be used for any initialization needs. +`init/3`, is common to all handlers. It receives three arguments: +a tuple containing the transport and protocol in use, the `Req` object +and the handler options you defined in the routes. In the context of +HTTP handlers this should be used for any initialization needs. For +example you can initialize here the `State` variable that will be +passed to the following functions. The second callback, `handle/2`, is where most of your code should -be. As the name explains, this is where you handle the request. +be. It receives two arguments: the `Req` object and the `State` +previously defined. As the name explains, this is where you handle +the request. The last callback, `terminate/3`, will be empty most of the time. -It's used for any needed cleanup. If you used the process dictionary, -timers, monitors then you most likely want to stop them in this -callback, as Cowboy might end up reusing this process for subsequent -requests. Please see the Internals chapter for more information. +It receives three arguments: the `Reason` for termination, the `Req` +object and the `State` previously defined. This callback should be +used strictly for cleaning up. Replying using the `Req` is disallowed. +If you used the process dictionary, timers, monitors then you most +likely want to stop them in this callback, as Cowboy might end up +reusing this process for subsequent requests. Please see the +Internals chapter for more information. Of course the general advice is to not use the process dictionary, and that any operation requiring reception of messages should be diff --git a/guide/introduction.md b/guide/introduction.md index e5616b0..a7f35a2 100644 --- a/guide/introduction.md +++ b/guide/introduction.md @@ -108,8 +108,10 @@ handlers, Websocket handlers, REST handlers and static handlers. Their usage is documented in the respective sections of the guide. Most applications use the plain HTTP handler, which has three callback -functions: init/3, handle/2 and terminate/3. Following is an example of -a simple handler module. +functions: init/3, handle/2 and terminate/3. You can find more information +about the arguments and possible return values of these callbacks in the +HTTP handlers section of this guide. Following is an example of a simple +HTTP handler module. ``` erlang -module(my_handler). |