diff options
author | Loïc Hoguin <[email protected]> | 2013-05-17 13:13:27 +0200 |
---|---|---|
committer | Loïc Hoguin <[email protected]> | 2013-05-17 13:13:27 +0200 |
commit | 666c59bc422172562673916ed3a8a796c4f9fbf4 (patch) | |
tree | f561151846de077513fa767edc10165a469d09ef /manual/cowboy_loop_handler.md | |
parent | 0e0ec7b1203a8490ee9a876f9274fe0c64e708f8 (diff) | |
download | cowboy-666c59bc422172562673916ed3a8a796c4f9fbf4.tar.gz cowboy-666c59bc422172562673916ed3a8a796c4f9fbf4.tar.bz2 cowboy-666c59bc422172562673916ed3a8a796c4f9fbf4.zip |
Add the Cowboy Function Reference
The manual details every stable public functions of Cowboy.
Diffstat (limited to 'manual/cowboy_loop_handler.md')
-rw-r--r-- | manual/cowboy_loop_handler.md | 91 |
1 files changed, 91 insertions, 0 deletions
diff --git a/manual/cowboy_loop_handler.md b/manual/cowboy_loop_handler.md new file mode 100644 index 0000000..ccbb9b0 --- /dev/null +++ b/manual/cowboy_loop_handler.md @@ -0,0 +1,91 @@ +cowboy_loop_handler +=================== + +The `cowboy_loop_handler` behaviour defines the interface used +by HTTP handlers that do not send a response directly, instead +requiring a receive loop to process Erlang messages. + +This interface is best fit for long-polling types of requests. + +The `init/3` callback will always be called, followed by zero +or more calls to `info/3`. The `terminate/3` will always be +called last. + +Types +----- + +None. + +Callbacks +--------- + +### init({TransportName, ProtocolName}, Req, Opts) + -> {loop, Req, State} + | {loop, Req, State, hibernate} + | {loop, Req, State, Timeout} + | {loop, Req, State, Timeout, hibernate} + | {shutdown, Req, State} + +> Types: +> * TransportName = tcp | ssl | atom() +> * ProtocolName = http | atom() +> * Req = cowboy_req:req() +> * Opts = any() +> * State = any() +> * Timeout = timeout() +> +> Initialize the state for this request. +> +> This callback will typically be used to register this process +> to an event manager or a message queue in order to receive +> the messages the handler wants to process. +> +> The receive loop will run for a duration of up to `Timeout` +> milliseconds after it last received data from the socket, +> at which point it will stop and send a `204 No Content` reply. +> By default this value is set to `infinity`. It is recommended +> to either set this value or ensure by any other mechanism +> that the handler will be closed after a certain period of +> inactivity. +> +> The `hibernate` option will hibernate the process until it +> starts receiving messages. +> +> The `shutdown` return value can be used to skip the receive +> loop entirely. + +### info(Info, Req, State) -> {ok, Req, State} | {loop, Req, State} + | {loop, Req, State, hibernate} + +> Types: +> * Info = any() +> * Req = cowboy_req:req() +> * State = any() +> +> Handle the Erlang message received. +> +> This function will be called every time an Erlang message +> has been received. The message can be any Erlang term. +> +> The `ok` return value can be used to stop the receive loop, +> typically because a response has been sent. +> +> The `hibernate` option will hibernate the process until +> it receives another message. + +### terminate(Reason, Req, State) -> ok + +> Types: +> * Reason = {normal, shutdown} | {normal, timeout} | {error, closed} | {error, overflow} | {error, atom()} +> * Req = cowboy_req:req() +> * State = any() +> +> Perform any necessary cleanup of the state. +> +> This callback will typically unregister from any event manager +> or message queue it registered to in `init/3`. +> +> 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. |