Permalink
Browse files

Fix Markdown in the guide

  • Loading branch information...
1 parent eec2e40 commit 7ceb7889d54f38469889c78a3a7118e86d0dd861 @essen essen committed Nov 12, 2012
Showing with 69 additions and 69 deletions.
  1. +7 −7 guide/embedded.md
  2. +10 −10 guide/internals.md
  3. +19 −19 guide/listeners.md
  4. +7 −7 guide/protocols.md
  5. +26 −26 guide/transports.md
View
@@ -13,22 +13,22 @@ Embedding
---------
To embed Ranch in your application you can simply add the child specs
-to your supervision tree. This can all be done in the ```init/1``` function
+to your supervision tree. This can all be done in the `init/1` function
of one of your application supervisors.
Ranch requires at the minimum two kinds of child specs for embedding.
-First, you need to add ```ranch_sup``` to your supervision tree, only once,
+First, you need to add `ranch_sup` to your supervision tree, only once,
regardless of the number of listeners you will use. Then you need to
add the child specs for each listener.
Ranch has a convenience function for getting the listeners child specs
-called ```ranch:child_spec/6```, that works like ```ranch:start_listener/6```,
+called `ranch:child_spec/6`, that works like `ranch:start_listener/6`,
except that it doesn't start anything, it only returns child specs.
-As for ```ranch_sup```, the child spec is simple enough to not require a
+As for `ranch_sup`, the child spec is simple enough to not require a
convenience function.
-The following example adds both ```ranch_sup``` and one listener to another
+The following example adds both `ranch_sup` and one listener to another
application's supervision tree.
``` erlang
@@ -43,8 +43,8 @@ init([]) ->
```
Remember, you can add as many listener child specs as needed, but only
-one ```ranch_sup``` spec!
+one `ranch_sup` spec!
It is recommended that your architecture makes sure that all listeners
-are restarted if ```ranch_sup``` fails. See the Ranch internals chapter for
+are restarted if `ranch_sup` fails. See the Ranch internals chapter for
more details on how Ranch does it.
View
@@ -11,34 +11,34 @@ Architecture
Ranch is an OTP application.
Like all OTP applications, Ranch has a top supervisor. It is responsible
-for supervising the ```ranch_server``` process and all the listeners that
+for supervising the `ranch_server` process and all the listeners that
will be started.
-The ```ranch_server``` gen_server is the central process keeping track of the
+The `ranch_server` gen_server is the central process keeping track of the
listeners, the acceptors and the connection processes. It does so through
-the use of a public ets table called ```ranch_server``` too. This allows
+the use of a public ets table called `ranch_server` too. This allows
some operations to be sequential by going through the gen_server, while
others just query the ets table directly, ensuring there is no bottleneck
for the most common operations.
Because the most common operation is keeping track of the number of
connections currently being used for each listener, the ets table
-has ```write_concurrency``` enabled, allowing us to perform all these
-operations concurrently using ```ets:update_counter/3```. To read the number
+has `write_concurrency` enabled, allowing us to perform all these
+operations concurrently using `ets:update_counter/3`. To read the number
of connections we simply increment the counter by 0, which allows us
to stay in a write context and still receive the counter's value.
For increased fault tolerance, the owner of the ets table is
-```ranch_sup``` and not ```ranch_server``` as you could expect. This way,
-if the ```ranch_server``` gen_server fails, it doesn't lose any information
+`ranch_sup` and not `ranch_server` as you could expect. This way,
+if the `ranch_server` gen_server fails, it doesn't lose any information
and the restarted process can continue as if nothing happened. Note that
this usage is not recommended by OTP.
-Listeners are grouped into the ```ranch_listener_sup``` supervisor and
+Listeners are grouped into the `ranch_listener_sup` supervisor and
consist of three kinds of processes: the listener gen_server, the
acceptor processes and the connection processes, both grouped under
their own supervisor. All of these processes are registered to the
-```ranch_server``` gen_server with varying amount of information.
+`ranch_server` gen_server with varying amount of information.
All socket operations, including listening for connections, go through
transport handlers. Accepted connections are given to the protocol handler.
@@ -58,7 +58,7 @@ system.
* * *
-The second argument to ```ranch:start_listener/6``` is the number of
+The second argument to `ranch:start_listener/6` is the number of
processes that will be accepting connections. Care should be taken
when choosing this number.
View
@@ -28,21 +28,21 @@ When starting a listener, a number of different settings are required:
* A protocol handler and its associated options.
Ranch includes both TCP and SSL transport handlers, respectively
-```ranch_tcp``` and ```ranch_ssl```.
+`ranch_tcp` and `ranch_ssl`.
-A listener can be started by calling the ```ranch:start_listener/6```
-function. Before doing so however, you must ensure that the ```ranch```
+A listener can be started by calling the `ranch:start_listener/6`
+function. Before doing so however, you must ensure that the `ranch`
application is started.
-To start the ```ranch``` application:
+To start the `ranch` application:
``` erlang
ok = application:start(ranch).
```
-You are then ready to start a listener. Let's call it ```tcp_echo```. It will
+You are then ready to start a listener. Let's call it `tcp_echo`. It will
have a pool of 100 acceptors, use a TCP transport and forward connections
-to the ```echo_protocol``` handler.
+to the `echo_protocol` handler.
``` erlang
{ok, _} = ranch:start_listener(tcp_echo, 100,
@@ -51,8 +51,8 @@ to the ```echo_protocol``` handler.
).
```
-You can try this out by compiling and running the ```tcp_echo``` example in the
-examples directory. To do so, open a shell in the ```examples/tcp_echo/```
+You can try this out by compiling and running the `tcp_echo` example in the
+examples directory. To do so, open a shell in the `examples/tcp_echo/`
directory and run the following commands:
```
@@ -63,8 +63,8 @@ Listening on port 5555
You can then connect to it using telnet and see the echo server reply
everything you send to it. Then when you're done testing, you can use
-the ```Ctrl+]``` key to escape to the telnet command line and type
-```quit``` to exit.
+the `Ctrl+]` key to escape to the telnet command line and type
+`quit` to exit.
```
% telnet localhost 5555
@@ -88,8 +88,8 @@ You do not have to specify a specific port to listen on. If you give
the port number 0, or if you omit the port number entirely, Ranch will
start listening on a random port.
-You can retrieve this port number by calling ```ranch:get_port/1```. The
-argument is the name of the listener you gave in ```ranch:start_listener/6```.
+You can retrieve this port number by calling `ranch:get_port/1`. The
+argument is the name of the listener you gave in `ranch:start_listener/6`.
``` erlang
{ok, _} = ranch:start_listener(tcp_echo, 100,
@@ -109,7 +109,7 @@ used although that's a less efficient solution.
Limiting the number of concurrent connections
---------------------------------------------
-The ```max_connections``` transport option allows you to limit the number
+The `max_connections` transport option allows you to limit the number
of concurrent connections. It defaults to 1024. Its purpose is to
prevent your system from being overloaded and ensuring all the
connections are handled optimally.
@@ -121,7 +121,7 @@ connections are handled optimally.
).
```
-You can disable this limit by setting its value to the atom ```infinity```.
+You can disable this limit by setting its value to the atom `infinity`.
``` erlang
{ok, _} = ranch:start_listener(tcp_echo, 100,
@@ -131,29 +131,29 @@ You can disable this limit by setting its value to the atom ```infinity```.
```
You may not always want connections to be counted when checking for
-```max_connections```. For example you might have a protocol where both
+`max_connections`. For example you might have a protocol where both
short-lived and long-lived connections are possible. If the long-lived
connections are mostly waiting for messages, then they don't consume
much resources and can safely be removed from the count.
To remove the connection from the count, you must call the
-```ranch_listener:remove_connection/1``` from within the connection process,
+`ranch_listener:remove_connection/1` from within the connection process,
with the listener pid as the only argument.
``` erlang
ranch_listener:remove_connection(ListenerPid).
```
As seen in the chapter covering protocols, this pid is received as the
-first argument of the protocol's ```start_link/4``` callback.
+first argument of the protocol's `start_link/4` callback.
Upgrading
---------
Ranch allows you to upgrade the protocol options. This takes effect
immediately and for all subsequent connections.
-To upgrade the protocol options, call ```ranch:set_protocol_options/2```
+To upgrade the protocol options, call `ranch:set_protocol_options/2`
with the name of the listener as first argument and the new options
as the second.
@@ -164,7 +164,7 @@ ranch:set_protocol_options(tcp_echo, NewOpts).
All future connections will use the new options.
You can also retrieve the current options similarly by
-calling ```ranch:get_protocol_options/1```.
+calling `ranch:get_protocol_options/1`.
``` erlang
Opts = ranch:get_protocol_options(tcp_echo).
View
@@ -10,16 +10,16 @@ protocol logic executed in this process.
Writing a protocol handler
--------------------------
-All protocol handlers must implement the ```ranch_protocol``` behavior
-which defines a single callback, ```start_link/4```. This callback is
+All protocol handlers must implement the `ranch_protocol` behavior
+which defines a single callback, `start_link/4`. This callback is
responsible for spawning a new process for handling the connection.
It receives four arguments: the listener's pid, the socket, the
transport handler being used and the protocol options defined in
-the call to ```ranch:start_listener/6```. This callback must
-return ```{ok, Pid}```, with ```Pid``` the pid of the new process.
+the call to `ranch:start_listener/6`. This callback must
+return `{ok, Pid}`, with `Pid` the pid of the new process.
The newly started process can then freely initialize itself. However,
-it must call ```ranch:accept_ack/1``` before doing any socket operation.
+it must call `ranch:accept_ack/1` before doing any socket operation.
This will ensure the connection process is the owner of the socket.
It expects the listener's pid as argument.
@@ -29,11 +29,11 @@ ok = ranch:accept_ack(ListenerPid).
If your protocol code requires specific socket options, you should
set them while initializing your connection process and before
-starting ```ranch:accept_ack/1```. You can use ```Transport:setopts/2```
+starting `ranch:accept_ack/1`. You can use `Transport:setopts/2`
for that purpose.
Following is the complete protocol code for the example found
-in ```examples/tcp_echo/```.
+in `examples/tcp_echo/`.
``` erlang
-module(echo_protocol).
View
@@ -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.

0 comments on commit 7ceb788

Please sign in to comment.