diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 57 |
1 files changed, 3 insertions, 54 deletions
@@ -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``` |