diff options
Diffstat (limited to 'guide/transports.md')
| -rw-r--r-- | guide/transports.md | 52 |
1 files changed, 26 insertions, 26 deletions
diff --git a/guide/transports.md b/guide/transports.md index 4fee94a..910d3ce 100644 --- a/guide/transports.md +++ b/guide/transports.md @@ -14,39 +14,39 @@ are initialized as passive. TCP transport ------------- -The TCP transport is a thin wrapper around ```gen_tcp```. +The TCP transport is a thin wrapper around `gen_tcp`. SSL transport ------------- -The SSL transport is a thin wrapper around ```ssl```. It requires -the ```crypto```, ```public_key``` and ```ssl``` applications to be started. +The SSL transport is a thin wrapper around `ssl`. It requires +the `crypto`, `public_key` and `ssl` applications to be started. You can start each of them individually, or you can call the -```ssl:start/0``` convenience function. +`ssl:start/0` convenience function. ``` erlang ssl:start(). ``` In a proper OTP setting, you will need to make your application -depend on the ```crypto```, ```public_key``` and ```ssl``` applications. +depend on the `crypto`, `public_key` and `ssl` applications. They will be started automatically when starting your release. -The SSL transport ```accept/2``` function performs both transport +The SSL transport `accept/2` function performs both transport and SSL accepts. Errors occurring during the SSL accept phase -are returned as ```{error, {ssl_accept, atom()}}``` to differentiate +are returned as `{error, {ssl_accept, atom()}}` to differentiate on which socket the problem occurred. Sending and receiving data -------------------------- -This section assumes that ```Transport``` is a valid transport handler -(like ```ranch_tcp``` or ```ranch_ssl```) and ```Socket``` is a connected +This section assumes that `Transport` is a valid transport handler +(like `ranch_tcp` or `ranch_ssl`) and `Socket` is a connected socket obtained through the listener. -You can send data to a socket by calling the ```Transport:send/2``` -function. The data can be given as ```iodata()```, which is defined as -```binary() | iolist()```. All the following calls will work: +You can send data to a socket by calling the `Transport:send/2` +function. The data can be given as `iodata()`, which is defined as +`binary() | iolist()`. All the following calls will work: ``` erlang Transport:send(Socket, <<"Ranch is cool!">>). @@ -56,7 +56,7 @@ Transport:send(Socket, ["Ranch", [<<"is">>, "cool!"]]). ``` You can receive data either in passive or in active mode. Passive mode -means that you will perform a blocking ```Transport:recv/2``` call, while +means that you will perform a blocking `Transport:recv/2` call, while active mode means that you will receive the data as a message. By default, all data will be received as binary. It is possible to @@ -65,7 +65,7 @@ are a more efficient construct, especially for binary protocols. Receiving data using passive mode requires a single function call. The first argument is the socket, and the third argument is a timeout duration -before the call returns with ```{error, timeout}```. +before the call returns with `{error, timeout}`. The second argument is the amount of data in bytes that we want to receive. The function will wait for data until it has received exactly this amount. @@ -79,27 +79,27 @@ this call return as soon as data was read, regardless of its size. Active mode requires you to inform the socket that you want to receive data as a message and to write the code to actually receive it. -There are two kinds of active modes: ```{active, once}``` and -```{active, true}```. The first will send a single message before going +There are two kinds of active modes: `{active, once}` and +`{active, true}`. The first will send a single message before going back to passive mode; the second will send messages indefinitely. -We recommend not using the ```{active, true}``` mode as it could quickly +We recommend not using the `{active, true}` mode as it could quickly flood your process mailbox. It's better to keep the data in the socket and read it only when required. Three different messages can be received: - * ```{OK, Socket, Data}``` - * ```{Closed, Socket}``` - * ```{Error, Socket, Reason}``` + * `{OK, Socket, Data}` + * `{Closed, Socket}` + * `{Error, Socket, Reason}` -The value of ```OK```, ```Closed``` and ```Error``` can be different +The value of `OK`, `Closed` and `Error` can be different depending on the transport being used. To be able to properly match -on them you must first call the ```Transport:messages/0``` function. +on them you must first call the `Transport:messages/0` function. ``` erlang {OK, Closed, Error} = Transport:messages(). ``` -To start receiving messages you will need to call the ```Transport:setopts/2``` +To start receiving messages you will need to call the `Transport:setopts/2` function, and do so every time you want to receive data. ``` erlang @@ -121,12 +121,12 @@ you really need is just a few more clauses when receiving messages. Writing a transport handler --------------------------- -A transport handler is a module implementing the ```ranch_transport``` behavior. +A transport handler is a module implementing the `ranch_transport` behavior. It defines a certain number of callbacks that must be written in order to allow transparent usage of the transport handler. The behavior doesn't define the socket options available when opening a socket. These do not need to be common to all transports as it's easy enough to write different initialization functions for the different transports that -will be used. With one exception though. The ```setopts/2``` function *must* -implement the ```{active, once}``` and the ```{active, true}``` options. +will be used. With one exception though. The `setopts/2` function *must* +implement the `{active, once}` and the `{active, true}` options. |