From 4156fa3ebb978a21b52abf94202bb3d7676f4c03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Thu, 12 Apr 2012 23:22:52 +0200 Subject: Import the acceptor code from Cowboy Modules were renamed. The 'cowboy_' prefix became 'ranch_'. At the same time, ranch_ssl_transport became ranch_ssl, and ranch_tcp_transport became ranch_tcp, because appending '_transport' felt a bit redundant considering SSL and TCP clearly are transports. One test has been added to make sure everything is working. --- README.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 88 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 551c502..2fbe9cd 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,91 @@ Ranch ===== -Ranch is a socket acceptor pool, able to accept connections for any kind -of TCP protocol. +Ranch is a socket acceptor pool for TCP protocols. + +Goals +----- + +Ranch aims to provide everything you need to accept TCP connections with +a **small** code base and **low latency** while being easy to use directly +as an application or to **embed** into your own. + +Ranch provides a **modular** design, letting you choose which transport +and protocol are going to be used for a particular listener. Listeners +accept and manage connections on one port, and include facilities to +limit the number of **concurrent** connections. Connections are sorted +into **pools**, each pool having a different configurable limit. + +Ranch also allows you to **upgrade** the acceptor pool without having +to close any of the currently opened sockets. + +The project is currently in early development. Comments and suggestions are +more than welcome. To contribute, either open bug reports, or fork the project +and send us pull requests with new or improved functionality. You should +discuss your plans with us before doing any serious work, though, to avoid +duplicating efforts. + +Quick start +----------- + +* Add Ranch as a rebar or agner dependency to your application. +* Start Ranch and add one or more listeners. +* Write protocol handlers for your application. + +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 Transport:setopts/2 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. -- cgit v1.2.3