Skip to content


Subversion checkout URL

You can clone with
Download ZIP
100644 92 lines (70 sloc) 3.57 KB
f971ec1 Initial commit.
Loïc Hoguin authored
1 Ranch
2 =====
4156fa3 Import the acceptor code from Cowboy
Loïc Hoguin authored
4 Ranch is a socket acceptor pool for TCP protocols.
6 Goals
7 -----
9 Ranch aims to provide everything you need to accept TCP connections with
10 a **small** code base and **low latency** while being easy to use directly
11 as an application or to **embed** into your own.
13 Ranch provides a **modular** design, letting you choose which transport
14 and protocol are going to be used for a particular listener. Listeners
15 accept and manage connections on one port, and include facilities to
16 limit the number of **concurrent** connections. Connections are sorted
17 into **pools**, each pool having a different configurable limit.
19 Ranch also allows you to **upgrade** the acceptor pool without having
20 to close any of the currently opened sockets.
22 The project is currently in early development. Comments and suggestions are
23 more than welcome. To contribute, either open bug reports, or fork the project
24 and send us pull requests with new or improved functionality. You should
25 discuss your plans with us before doing any serious work, though, to avoid
26 duplicating efforts.
28 Quick start
29 -----------
31 * Add Ranch as a rebar or agner dependency to your application.
32 * Start Ranch and add one or more listeners.
33 * Write protocol handlers for your application.
35 Getting Started
36 ---------------
38 Ranch accepts connections received on a given port and using a given
39 transport, like TCP or SSL, and forward them to a given protocol
40 handler. Acceptors and protocol handler processes are of course
41 supervised automatically.
43 Ranch does nothing by default. You need to explicitly request Ranch
44 to listen on a port with your chosen transport and protocol handlers.
45 To do so, you must start a listener.
47 A listener is a special kind of supervisor that manages both the
48 acceptor pool and the protocol processes. It is named and can thus be
49 started and stopped at will.
51 An acceptor pool is a pool of processes whose only role is to accept
52 new connections. It's good practice to have many of these processes
53 as they are very cheap and allow much quicker response when you get
54 many connections. Of course, as with everything else, you should
55 **benchmark** before you decide what's best for you.
57 Ranch includes both TCP and SSL transport handlers, abstracted through
58 a single common interface.
60 You can start and stop listeners by calling `ranch:start_listener/6` and
61 `ranch:stop_listener/1` respectively.
63 The following example demonstrates the startup of a very simple listener.
65 ``` erlang
66 application:start(ranch),
67 %% Name, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts
68 ranch:start_listener(my_echo_listener, 100,
69 ranch_tcp, [{port, 1234}],
70 my_echo_protocol, [{log, "echo.log"}]
71 ).
72 ```
74 Writing a protocol handler
75 --------------------------
77 The only exported function a protocol handler needs is the start_link/4
78 function, with arguments ListenerPid, Socket, Transport and Opts. ListenerPid
79 is the pid to the listener's gen_server, managing the connections. Socket is of
80 course the client socket; Transport is the module name of the chosen transport
81 handler and Opts is protocol options defined when starting the listener.
83 After initializing your protocol, it is recommended to call the
84 function ranch:accept_ack/1 with the ListenerPid as argument,
85 as it will ensure Ranch has been able to fully initialize the socket.
86 Anything you do past this point is up to you!
88 If you need to change some socket options, like enabling raw mode for example,
89 you can call the <em>Transport:setopts/2</em> function. It is the protocol's
90 responsability to manage the socket usage, there should be no need for an user
91 to specify that kind of options while starting a listener.
Something went wrong with that request. Please try again.