diff options
| -rw-r--r-- | doc/src/manual/cowboy_handler.asciidoc | 114 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_handler.terminate.asciidoc | 64 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_websocket.asciidoc | 2 |
3 files changed, 107 insertions, 73 deletions
diff --git a/doc/src/manual/cowboy_handler.asciidoc b/doc/src/manual/cowboy_handler.asciidoc index fbbe761..28ac311 100644 --- a/doc/src/manual/cowboy_handler.asciidoc +++ b/doc/src/manual/cowboy_handler.asciidoc @@ -2,98 +2,68 @@ == Name -cowboy_handler - handler middleware and behaviour +cowboy_handler - Plain HTTP handlers == Description -The `cowboy_handler` middleware executes the handler passed -through the environment values `handler` and `handler_opts`, -and adds the result of this execution to the environment as -the value `result`, indicating that the request has been -handled and received a response. +The `cowboy_handler` middleware executes the handler selected +by the router or any other preceding middleware. -Environment input: +This middleware takes the handler module and initial state +from the `handler` and `handler_opts` environment values, +respectively. On completion, it adds a `result` value to +the middleware environment, containing the return value +of the `terminate/3` callback (if defined) and `ok` otherwise. -handler = module():: Handler to be executed. -handler_opts = any():: Options to be passed to the handler. - -Environment output: - -result = ok:: Result of the request. - -This module also defines the `cowboy_handler` behaviour that -defines the basic interface for handlers. All Cowboy handlers -implement at least the `init/2` callback, and may implement -the `terminate/3` callback optionally. - -== Terminate reasons - -The following values may be received as the terminate reason -in the optional `terminate/3` callback. Different handler types -may define additional terminate reasons. - -normal:: - The connection was closed normally. - -{crash, Class, Reason}:: - A crash occurred in the handler. `Class` and `Reason` can be - used to obtain more information about the crash. The function - `erlang:get_stacktrace/0` can also be called to obtain the - stacktrace of the process when the crash occurred. +This module also defines a callback interface for handling +HTTP requests. == Callbacks -=== init(Req, Opts) -> {ok, Req, State} | {Module, Req, State} | {Module, Req, State, hibernate | Timeout} | {Module, Req, State, Timeout, hibernate} +Plain HTTP handlers implement the following interface: -Req = cowboy_req:req():: The Req object. -Opts = any():: Handler options. -State = any():: Handler state. -Module = module():: Module of the sub-protocol to use. -Timeout = timeout():: Timeout passed to the sub-protocol, when applicable. +[source,erlang] +---- +init(Req, State) -> {ok, Req, State} -Process the request. +terminate(Reason, Req, State) -> ok %% optional -This function can be used to switch to an alternate handler -type by returning the name of the module to be used, along -with a few options. +Req :: cowboy_req:req() +State :: any() +Reason :: normal + | {crash, error | exit | throw, any()} +---- -For basic handlers this is the function where the response -should be sent. If no response is sent, Cowboy will ensure -that a `204 No Content` response is sent. +These two callbacks are common to all handlers. -A crash in this callback will result in `terminate/3` being -called if it is defined, with the `State` argument set to -the value of `Opts` originally given to the `init/2` callback. +Plain HTTP handlers do all their work in the `init/2` +callback. Returning `ok` terminates the handler. If no +response is sent, Cowboy will send a `204 No Content`. -=== terminate(Reason, Req, State) -> ok +The optional `terminate/3` callback will ultimately be called +with the reason for the termination of the handler. +Cowboy will terminate the process right after this. There +is no need to perform any cleanup in this callback. -Reason = any():: Reason for termination. -Req = cowboy_req:req():: The Req object. -State = any():: Handler state. +The following terminate reasons are defined for plain HTTP +handlers: -Perform any necessary cleanup of the state. - -This callback should release any resource currently in use, -clear any active timer and reset the process to its original -state, as it might be reused for future requests sent on the -same connection. Typical plain HTTP handlers rarely need to -use it. +normal:: + The connection was closed normally. -A crash in this callback or an invalid return value will -result in the closing of the connection and the termination -of the process. +{crash, Class, Reason}:: + A crash occurred in the handler. `Class` and `Reason` can be + used to obtain more information about the crash. The function + `erlang:get_stacktrace/0` can also be called to obtain the + stacktrace of the process when the crash occurred. == Exports -=== terminate(Reason, Req, State, Handler) -> ok +The following function should be called by modules implementing +custom handlers to execute the optional terminate callback: -Reason = any():: Reason for termination. -Req = cowboy_req:req():: The Req object. -State = any():: Handler state. -Handler = module():: Handler module. +* link:man:cowboy_handler:terminate(3)[cowboy_handler:terminate(3)] - Terminate the handler -Call the optional `terminate/3` callback if it exists. +== See also -This function should always be called at the end of the execution -of a handler, to give it a chance to clean up or perform -miscellaneous operations. +link:man:cowboy(7)[cowboy(7)] diff --git a/doc/src/manual/cowboy_handler.terminate.asciidoc b/doc/src/manual/cowboy_handler.terminate.asciidoc new file mode 100644 index 0000000..f10d945 --- /dev/null +++ b/doc/src/manual/cowboy_handler.terminate.asciidoc @@ -0,0 +1,64 @@ += cowboy_handler:terminate(3) + +== Name + +cowboy_handler:terminate - Terminate the handler + +== Description + +[source,erlang] +---- +terminate(Reason, Req | undefined, State, Handler) -> ok + +Reason :: any() +Req :: cowboy_req:req() +State :: any() +Handler :: module() +---- + +Call the optional terminate callback if it is defined. + +Make sure to use this function at the end of the execution +of modules that implement custom handler behaviors. + +== Arguments + +Reason:: + +Reason for termination. + +Req:: + +The Req object. ++ +It is possible to pass `undefined` if the handler has no concept +of requests/responses and discarded the Req object before calling +this function. + +State:: + +Handler state. + +Handler:: + +Handler module. + +== Return value + +The atom `ok` is always returned. It can be safely ignored. + +== Changelog + +* *2.0*: Function introduced. + +== Examples + +.Terminate a handler normally +[source,erlang] +---- +cowboy_handler:terminate(normal, Req, State, Handler). +---- + +== See also + +link:man:cowboy_handler(3)[cowboy_handler(3)] diff --git a/doc/src/manual/cowboy_websocket.asciidoc b/doc/src/manual/cowboy_websocket.asciidoc index a884811..3ae811a 100644 --- a/doc/src/manual/cowboy_websocket.asciidoc +++ b/doc/src/manual/cowboy_websocket.asciidoc @@ -52,7 +52,7 @@ websocket_init(State) -> CallResult %% optional websocket_handle(InFrame, State) -> CallResult websocket_info(Info, State) -> CallResult -terminate(Reason, undefined, State) -> any() %% optional +terminate(Reason, undefined, State) -> ok %% optional Req :: cowboy_req:req() State :: any() |