aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2012-08-22 13:07:00 +0200
committerLoïc Hoguin <[email protected]>2012-08-22 13:17:24 +0200
commit85510e373fa6db2b6faca0ef0e7081cf99dba146 (patch)
treece558b6a8122a42a2f317c087299a1609f57db91 /README.md
parent9cafa5e675065993c117cd94cc903248f5c97991 (diff)
downloadranch-85510e373fa6db2b6faca0ef0e7081cf99dba146.tar.gz
ranch-85510e373fa6db2b6faca0ef0e7081cf99dba146.tar.bz2
ranch-85510e373fa6db2b6faca0ef0e7081cf99dba146.zip
Add initial Ranch guide
Diffstat (limited to 'README.md')
-rw-r--r--README.md57
1 files changed, 3 insertions, 54 deletions
diff --git a/README.md b/README.md
index 2fbe9cd..08aea1e 100644
--- a/README.md
+++ b/README.md
@@ -35,57 +35,6 @@ Quick start
Getting Started
---------------
-Ranch accepts connections received on a given port and using a given
-transport, like TCP or SSL, and forward them to a given protocol
-handler. Acceptors and protocol handler processes are of course
-supervised automatically.
-
-Ranch does nothing by default. You need to explicitly request Ranch
-to listen on a port with your chosen transport and protocol handlers.
-To do so, you must start a listener.
-
-A listener is a special kind of supervisor that manages both the
-acceptor pool and the protocol processes. It is named and can thus be
-started and stopped at will.
-
-An acceptor pool is a pool of processes whose only role is to accept
-new connections. It's good practice to have many of these processes
-as they are very cheap and allow much quicker response when you get
-many connections. Of course, as with everything else, you should
-**benchmark** before you decide what's best for you.
-
-Ranch includes both TCP and SSL transport handlers, abstracted through
-a single common interface.
-
-You can start and stop listeners by calling `ranch:start_listener/6` and
-`ranch:stop_listener/1` respectively.
-
-The following example demonstrates the startup of a very simple listener.
-
-``` erlang
-application:start(ranch),
-%% Name, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts
-ranch:start_listener(my_echo_listener, 100,
- ranch_tcp, [{port, 1234}],
- my_echo_protocol, [{log, "echo.log"}]
-).
-```
-
-Writing a protocol handler
---------------------------
-
-The only exported function a protocol handler needs is the start_link/4
-function, with arguments ListenerPid, Socket, Transport and Opts. ListenerPid
-is the pid to the listener's gen_server, managing the connections. Socket is of
-course the client socket; Transport is the module name of the chosen transport
-handler and Opts is protocol options defined when starting the listener.
-
-After initializing your protocol, it is recommended to call the
-function ranch:accept_ack/1 with the ListenerPid as argument,
-as it will ensure Ranch has been able to fully initialize the socket.
-Anything you do past this point is up to you!
-
-If you need to change some socket options, like enabling raw mode for example,
-you can call the <em>Transport:setopts/2</em> function. It is the protocol's
-responsability to manage the socket usage, there should be no need for an user
-to specify that kind of options while starting a listener.
+* [Read the guide](https://github.com/extend/ranch/blob/master/guide/toc.md)
+* Look at the examples in the ```examples/``` directory
+* Build API documentation with ```make docs```; open ```doc/index.html```