From 7ceb7889d54f38469889c78a3a7118e86d0dd861 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Mon, 12 Nov 2012 19:27:16 +0100 Subject: Fix Markdown in the guide --- guide/embedded.md | 14 +++++++------- guide/internals.md | 20 ++++++++++---------- guide/listeners.md | 38 +++++++++++++++++++------------------- guide/protocols.md | 14 +++++++------- guide/transports.md | 52 ++++++++++++++++++++++++++-------------------------- 5 files changed, 69 insertions(+), 69 deletions(-) diff --git a/guide/embedded.md b/guide/embedded.md index 82dab75..6cac064 100644 --- a/guide/embedded.md +++ b/guide/embedded.md @@ -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. diff --git a/guide/internals.md b/guide/internals.md index 2dfd457..cb1f955 100644 --- a/guide/internals.md +++ b/guide/internals.md @@ -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. diff --git a/guide/listeners.md b/guide/listeners.md index 63cdf81..59aa990 100644 --- a/guide/listeners.md +++ b/guide/listeners.md @@ -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,13 +131,13 @@ 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 @@ -145,7 +145,7 @@ 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 --------- @@ -153,7 +153,7 @@ 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). diff --git a/guide/protocols.md b/guide/protocols.md index 7db8fec..94fc1c0 100644 --- a/guide/protocols.md +++ b/guide/protocols.md @@ -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). 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. -- cgit v1.2.3