From 4023e7f4e429179fd9c2cce4487c33646c6bd327 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Thu, 14 Jan 2016 13:35:25 +0100 Subject: Convert the documentation to Asciidoc A few small revisions were made, and Erlang.mk has been updated. --- doc/src/guide/sub_protocols.ezdoc | 64 --------------------------------------- 1 file changed, 64 deletions(-) delete mode 100644 doc/src/guide/sub_protocols.ezdoc (limited to 'doc/src/guide/sub_protocols.ezdoc') diff --git a/doc/src/guide/sub_protocols.ezdoc b/doc/src/guide/sub_protocols.ezdoc deleted file mode 100644 index 54e57aa..0000000 --- a/doc/src/guide/sub_protocols.ezdoc +++ /dev/null @@ -1,64 +0,0 @@ -::: Sub protocols - -Sub protocols are used for creating new types of handlers that -provide extra functionality in a reusable way. Cowboy uses this -mechanism to provide its loop, REST and Websocket handlers. - -This chapter will explain how to create your own sub protocols -and handler types. - -:: Usage - -To switch to a sub protocol, the `init/2` callback must return -the name of the sub protocol module. Everything past this point -is handled by the sub protocol. - -``` erlang -init(Req, _Opts) -> - {cowboy_websocket, Req, #state{}}. -``` - -The return value may also have a `Timeout` value and/or the -atom `hibernate`. These options are useful for long living -connections. When they are not provided, the timeout value -defaults to `infinity` and the hibernate value to `run`. - -The following snippet switches to the `my_protocol` sub -protocol, sets the timeout value to 5 seconds and enables -hibernation: - -``` erlang -init(Req, _Opts) -> - {my_protocol, Req, #state{}, 5000, hibernate}. -``` - -If a sub protocol does not make use of these options, it should -crash if it receives anything other than the default values. - -:: Upgrade - -After the `init/2` function returns, Cowboy will then call the -`upgrade/6` function. This is the only callback defined by the -`cowboy_sub_protocol` behavior. - -The function is named `upgrade` because it mimics the mechanism -of HTTP protocol upgrades. For some sub protocols, like Websocket, -an actual upgrade is performed. For others, like REST, this is -only an upgrade at Cowboy's level and the client has nothing to -do about it. - -The upgrade callback receives the Req object, the middleware -environment, the handler and its options, and the aforementioned -timeout and hibernate values. - -``` erlang -upgrade(Req, Env, Handler, HandlerOpts, Timeout, Hibernate) -> - %% Sub protocol code here. -``` - -This callback is expected to behave like a middleware and to -return an updated environment and Req object. - -Sub protocols are expected to call the `cowboy_handler:terminate/4` -function when they terminate. This function will make sure that -the optional `terminate/3` callback is called, if present. -- cgit v1.2.3