diff options
Diffstat (limited to 'docs/en/ranch/1.3/guide/transports/index.html')
| -rw-r--r-- | docs/en/ranch/1.3/guide/transports/index.html | 218 |
1 files changed, 74 insertions, 144 deletions
diff --git a/docs/en/ranch/1.3/guide/transports/index.html b/docs/en/ranch/1.3/guide/transports/index.html index 103ae423..09bf93b3 100644 --- a/docs/en/ranch/1.3/guide/transports/index.html +++ b/docs/en/ranch/1.3/guide/transports/index.html @@ -62,179 +62,107 @@ <h1 class="lined-header"><span>Transports</span></h1> -<div class="paragraph"><p>A transport defines the interface to interact with a socket.</p></div> -<div class="paragraph"><p>Transports can be used for connecting, listening and accepting -connections, but also for receiving and sending data. Both -passive and active mode are supported, although all sockets -are initialized as passive.</p></div> -<div class="sect1"> +<p>A transport defines the interface to interact with a socket.</p> +<p>Transports can be used for connecting, listening and accepting connections, but also for receiving and sending data. Both passive and active mode are supported, although all sockets are initialized as passive.</p> <h2 id="_tcp_transport">TCP transport</h2> -<div class="sectionbody"> -<div class="paragraph"><p>The TCP transport is a thin wrapper around <code>gen_tcp</code>.</p></div> -</div> -</div> -<div class="sect1"> +<p>The TCP transport is a thin wrapper around <code>gen_tcp</code>.</p> <h2 id="_ssl_transport">SSL transport</h2> -<div class="sectionbody"> -<div class="paragraph"><p>The SSL transport is a thin wrapper around <code>ssl</code>.</p></div> -<div class="paragraph"><p>Ranch depends on <code>ssl</code> by default so any necessary -dependencies will start when Ranch is started. It is -possible to remove the dependency when the SSL transport -will not be used. Refer to your release build tool’s -documentation for more information.</p></div> -<div class="paragraph"><p>When embedding Ranch listeners that have an SSL transport, -your application must depend on the <code>ssl</code> application for -proper behavior.</p></div> -</div> -</div> -<div class="sect1"> +<p>The SSL transport is a thin wrapper around <code>ssl</code>.</p> +<p>Ranch depends on <code>ssl</code> by default so any necessary dependencies will start when Ranch is started. It is possible to remove the dependency when the SSL transport will not be used. Refer to your release build tool's documentation for more information.</p> +<p>When embedding Ranch listeners that have an SSL transport, your application must depend on the <code>ssl</code> application for proper behavior.</p> <h2 id="_sending_and_receiving_data">Sending and receiving data</h2> -<div class="sectionbody"> -<div class="paragraph"><p>This section assumes that <code>Transport</code> is a valid transport handler -(like <code>ranch_tcp</code> or <code>ranch_ssl</code>) and <code>Socket</code> is a connected -socket obtained through the listener.</p></div> -<div class="paragraph"><p>You can send data to a socket by calling the <code>Transport:send/2</code> -function. The data can be given as <code>iodata()</code>, which is defined as -<code>binary() | iolist()</code>. All the following calls will work:</p></div> -<div class="listingblock"> -<div class="title">Sending data to the socket</div> -<div class="content"><!-- Generator: GNU source-highlight +<p>This section assumes that <code>Transport</code> is a valid transport handler (like <code>ranch_tcp</code> or <code>ranch_ssl</code>) and <code>Socket</code> is a connected socket obtained through the listener.</p> +<p>You can send data to a socket by calling the <code>Transport:send/2</code> function. The data can be given as <code>iodata()</code>, which is defined as <code>binary() | iolist()</code>. All the following calls will work:</p> +<div class="listingblock"><div class="title">Sending data to the socket</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt><span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Ranch is cool!"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span> -<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #FF0000">"Ranch is cool!"</span>)<span style="color: #990000">.</span> -<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #FF0000">"is"</span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span> -<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #990000"><<</span><span style="color: #FF0000">"is"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>You can receive data either in passive or in active mode. Passive mode -means that you will perform a blocking <code>Transport:recv/3</code> call, while -active mode means that you will receive the data as a message.</p></div> -<div class="paragraph"><p>By default, all data will be received as binary. It is possible to -receive data as strings, although this is not recommended as binaries -are a more efficient construct, especially for binary protocols.</p></div> -<div class="paragraph"><p>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 <code>{error, timeout}</code>.</p></div> -<div class="paragraph"><p>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. -If you are not expecting a precise size, you can specify 0 which will make -this call return as soon as data was read, regardless of its size.</p></div> -<div class="listingblock"> -<div class="title">Receiving data from the socket in passive mode</div> -<div class="content"><!-- Generator: GNU source-highlight +<pre><tt><font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">send</font></b>(<font color="#009900">Socket</font>, <font color="#990000"><<</font><font color="#FF0000">"Ranch is cool!"</font><font color="#990000">>></font>)<font color="#990000">.</font> +<font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">send</font></b>(<font color="#009900">Socket</font>, <font color="#FF0000">"Ranch is cool!"</font>)<font color="#990000">.</font> +<font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">send</font></b>(<font color="#009900">Socket</font>, [<font color="#FF0000">"Ranch"</font>, [<font color="#FF0000">"is"</font>, <font color="#FF0000">"cool!"</font>]])<font color="#990000">.</font> +<font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">send</font></b>(<font color="#009900">Socket</font>, [<font color="#FF0000">"Ranch"</font>, [<font color="#990000"><<</font><font color="#FF0000">"is"</font><font color="#990000">>></font>, <font color="#FF0000">"cool!"</font>]])<font color="#990000">.</font></tt></pre> +</div></div> +<p>You can receive data either in passive or in active mode. Passive mode means that you will perform a blocking <code>Transport:recv/3</code> call, while active mode means that you will receive the data as a message.</p> +<p>By default, all data will be received as binary. It is possible to receive data as strings, although this is not recommended as binaries are a more efficient construct, especially for binary protocols.</p> +<p>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 <code>{error, timeout}</code>.</p> +<p>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. If you are not expecting a precise size, you can specify 0 which will make this call return as soon as data was read, regardless of its size.</p> +<div class="listingblock"><div class="title">Receiving data from the socket in passive mode</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">5000</span>)<span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>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.</p></div> -<div class="paragraph"><p>There are two kinds of active modes: <code>{active, once}</code> and -<code>{active, true}</code>. The first will send a single message before going -back to passive mode; the second will send messages indefinitely. -We recommend not using the <code>{active, true}</code> 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.</p></div> -<div class="paragraph"><p>Three different messages can be received:</p></div> -<div class="ulist"><ul> -<li> -<p> -<code>{OK, Socket, Data}</code> -</p> +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#009900">Data</font>} <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">recv</font></b>(<font color="#009900">Socket</font>, <font color="#993399">0</font>, <font color="#993399">5000</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>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.</p> +<p>There are two kinds of active modes: <code>{active, once}</code> and <code>{active, true}</code>. The first will send a single message before going back to passive mode; the second will send messages indefinitely. We recommend not using the <code>{active, true}</code> 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.</p> +<p>Three different messages can be received:</p> +<ul><li><code>{OK, Socket, Data}</code> </li> -<li> -<p> -<code>{Closed, Socket}</code> -</p> +<li><code>{Closed, Socket}</code> </li> -<li> -<p> -<code>{Error, Socket, Reason}</code> -</p> +<li><code>{Error, Socket, Reason}</code> </li> -</ul></div> -<div class="paragraph"><p>The value of <code>OK</code>, <code>Closed</code> and <code>Error</code> can be different -depending on the transport being used. To be able to properly match -on them you must first call the <code>Transport:messages/0</code> function.</p></div> -<div class="listingblock"> -<div class="title">Retrieving the transport’s active message identifiers</div> -<div class="content"><!-- Generator: GNU source-highlight +</ul> +<p>The value of <code>OK</code>, <code>Closed</code> and <code>Error</code> can be different depending on the transport being used. To be able to properly match on them you must first call the <code>Transport:messages/0</code> function.</p> +<div class="listingblock"><div class="title">Retrieving the transport's active message identifiers</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt>{<span style="color: #009900">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>()<span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>To start receiving messages you will need to call the <code>Transport:setopts/2</code> -function, and do so every time you want to receive data.</p></div> -<div class="listingblock"> -<div class="title">Receiving messages from the socket in active mode</div> -<div class="content"><!-- Generator: GNU source-highlight +<pre><tt>{<font color="#009900">OK</font>, <font color="#009900">Closed</font>, <font color="#009900">Error</font>} <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">messages</font></b>()<font color="#990000">.</font></tt></pre> +</div></div> +<p>To start receiving messages you will need to call the <code>Transport:setopts/2</code> function, and do so every time you want to receive data.</p> +<div class="listingblock"><div class="title">Receiving messages from the socket in active mode</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt>{<span style="color: #009900">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>(), -<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]), -<span style="font-weight: bold"><span style="color: #0000FF">receive</span></span> - {<span style="color: #009900">OK</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"data received: ~p~n"</span>, [<span style="color: #009900">Data</span>]); - {<span style="color: #009900">Closed</span>, <span style="color: #009900">Socket</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"socket got closed!~n"</span>); - {<span style="color: #009900">Error</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"error happened: ~p~n"</span>, [<span style="color: #009900">Reason</span>]) -<span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>You can easily integrate active sockets with existing Erlang code as all -you really need is just a few more clauses when receiving messages.</p></div> -</div> -</div> -<div class="sect1"> +<pre><tt>{<font color="#009900">OK</font>, <font color="#009900">Closed</font>, <font color="#009900">Error</font>} <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">messages</font></b>(), +<font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">setopts</font></b>(<font color="#009900">Socket</font>, [{<font color="#FF6600">active</font>, <font color="#FF6600">once</font>}]), +<b><font color="#0000FF">receive</font></b> + {<font color="#009900">OK</font>, <font color="#009900">Socket</font>, <font color="#009900">Data</font>} <font color="#990000">-></font> + <b><font color="#000000">io:format</font></b>(<font color="#FF0000">"data received: ~p~n"</font>, [<font color="#009900">Data</font>]); + {<font color="#009900">Closed</font>, <font color="#009900">Socket</font>} <font color="#990000">-></font> + <b><font color="#000000">io:format</font></b>(<font color="#FF0000">"socket got closed!~n"</font>); + {<font color="#009900">Error</font>, <font color="#009900">Socket</font>, <font color="#009900">Reason</font>} <font color="#990000">-></font> + <b><font color="#000000">io:format</font></b>(<font color="#FF0000">"error happened: ~p~n"</font>, [<font color="#009900">Reason</font>]) +<b><font color="#0000FF">end</font></b><font color="#990000">.</font></tt></pre> +</div></div> +<p>You can easily integrate active sockets with existing Erlang code as all you really need is just a few more clauses when receiving messages.</p> <h2 id="_sending_files">Sending files</h2> -<div class="sectionbody"> -<div class="paragraph"><p>As in the previous section it is assumed <code>Transport</code> is a valid transport -handler and <code>Socket</code> is a connected socket obtained through the listener.</p></div> -<div class="paragraph"><p>To send a whole file, with name <code>Filename</code>, over a socket:</p></div> -<div class="listingblock"> -<div class="title">Sending a file by filename</div> -<div class="content"><!-- Generator: GNU source-highlight +<p>As in the previous section it is assumed <code>Transport</code> is a valid transport handler and <code>Socket</code> is a connected socket obtained through the listener.</p> +<p>To send a whole file, with name <code>Filename</code>, over a socket:</p> +<div class="listingblock"><div class="title">Sending a file by filename</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>)<span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>Or part of a file, with <code>Offset</code> greater than or equal to 0, <code>Bytes</code> number of -bytes and chunks of size <code>ChunkSize</code>:</p></div> -<div class="listingblock"> -<div class="title">Sending part of a file by filename in chunks</div> -<div class="content"><!-- Generator: GNU source-highlight +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#009900">SentBytes</font>} <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">sendfile</font></b>(<font color="#009900">Socket</font>, <font color="#009900">Filename</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>Or part of a file, with <code>Offset</code> greater than or equal to 0, <code>Bytes</code> number of bytes and chunks of size <code>ChunkSize</code>:</p> +<div class="listingblock"><div class="title">Sending part of a file by filename in chunks</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt><span style="color: #009900">Opts</span> <span style="color: #990000">=</span> [{<span style="color: #FF6600">chunk_size</span>, <span style="color: #009900">ChunkSize</span>}], -{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>To improve efficiency when sending multiple parts of the same file it is also -possible to use a file descriptor opened in raw mode:</p></div> -<div class="listingblock"> -<div class="title">Sending a file opened in raw mode</div> -<div class="content"><!-- Generator: GNU source-highlight +<pre><tt><font color="#009900">Opts</font> <font color="#990000">=</font> [{<font color="#FF6600">chunk_size</font>, <font color="#009900">ChunkSize</font>}], +{<font color="#FF6600">ok</font>, <font color="#009900">SentBytes</font>} <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">sendfile</font></b>(<font color="#009900">Socket</font>, <font color="#009900">Filename</font>, <font color="#009900">Offset</font>, <font color="#009900">Bytes</font>, <font color="#009900">Opts</font>)<font color="#990000">.</font></tt></pre> +</div></div> +<p>To improve efficiency when sending multiple parts of the same file it is also possible to use a file descriptor opened in raw mode:</p> +<div class="listingblock"><div class="title">Sending a file opened in raw mode</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">RawFile</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:open</span></span>(<span style="color: #009900">Filename</span>, [<span style="color: #FF6600">raw</span>, <span style="color: #FF6600">read</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>]), -{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">RawFile</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div> -</div> -</div> -<div class="sect1"> +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#009900">RawFile</font>} <font color="#990000">=</font> <b><font color="#000000">file:open</font></b>(<font color="#009900">Filename</font>, [<font color="#FF6600">raw</font>, <font color="#FF6600">read</font>, <b><font color="#000080">binary</font></b>]), +{<font color="#FF6600">ok</font>, <font color="#009900">SentBytes</font>} <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">sendfile</font></b>(<font color="#009900">Socket</font>, <font color="#009900">RawFile</font>, <font color="#009900">Offset</font>, <font color="#009900">Bytes</font>, <font color="#009900">Opts</font>)<font color="#990000">.</font></tt></pre> +</div></div> <h2 id="_writing_a_transport_handler">Writing a transport handler</h2> -<div class="sectionbody"> -<div class="paragraph"><p>A transport handler is a module implementing the <code>ranch_transport</code> behavior. -It defines a certain number of callbacks that must be written in order to -allow transparent usage of the transport handler.</p></div> -<div class="paragraph"><p>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 <code>setopts/2</code> function <strong>must</strong> -implement the <code>{active, once}</code> and the <code>{active, true}</code> options.</p></div> -<div class="paragraph"><p>If the transport handler doesn’t have a native implementation of <code>sendfile/5</code> a -fallback is available, <code>ranch_transport:sendfile/6</code>. The extra first argument -is the transport’s module. See <code>ranch_ssl</code> for an example.</p></div> -</div> -</div> +<p>A transport handler is a module implementing the <code>ranch_transport</code> behavior. It defines a certain number of callbacks that must be written in order to allow transparent usage of the transport handler.</p> +<p>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 <code>setopts/2</code> function <strong>must</strong> implement the <code>{active, once}</code> and the <code>{active, true}</code> options.</p> +<p>If the transport handler doesn't have a native implementation of <code>sendfile/5</code> a fallback is available, <code>ranch_transport:sendfile/6</code>. The extra first argument is the transport's module. See <code>ranch_ssl</code> for an example.</p> + @@ -291,6 +219,8 @@ is the transport’s module. See <code>ranch_ssl</code> for an example.</p>< + <li><a href="/docs/en/ranch/1.5/guide">1.5</a></li> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> |