Ranch is a socket acceptor pool, able to accept connections for any kind of TCP protocol.
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 your 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.
- 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.
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.
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"}]
).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.
Note that while you technically can run a protocol handler directly as a gen_server or a gen_fsm, it's probably not a good idea, as the only call you'll ever receive from Ranch is the start_link/4 call. On the other hand, feel free to write a very basic protocol handler which then forwards requests to a gen_server or gen_fsm. By doing so however you must take care to supervise their processes as Ranch only knows about the protocol handler itself.