{ok, Socket} = ranch:handshake(Ref).
A protocol handler starts a connection process and defines the protocol logic executed in this process.
All protocol handlers must implement the ranch_protocol
behavior which defines a single callback, start_link/3
. This callback is responsible for spawning a new process for handling the connection. It receives three arguments: the name of the listener, the transport handler being used and the protocol options defined in the call to ranch:start_listener/5
. This callback must return {ok, Pid}
, with Pid
the pid of the new process.
The newly started process can then freely initialize itself. However, it must call ranch:handshake/1,2
before doing any socket operation. This will ensure the connection process is the owner of the socket. It expects the listener's name as argument.
{ok, Socket} = ranch:handshake(Ref).
If your protocol code requires specific socket options, you should set them while initializing your connection process, after calling ranch:handshake/1,2
. You can use Transport:setopts/2
for that purpose.
Following is the complete protocol code for the example found in examples/tcp_echo/
.
-module(echo_protocol). -behaviour(ranch_protocol). -export([start_link/3]). -export([init/3]). start_link(Ref, Transport, Opts) -> Pid = spawn_link(?MODULE, init, [Ref, Transport, Opts]), {ok, Pid}. init(Ref, Transport, _Opts = []) -> {ok, Socket} = ranch:handshake(Ref), loop(Socket, Transport). loop(Socket, Transport) -> case Transport:recv(Socket, 0, 5000) of {ok, Data} -> Transport:send(Socket, Data), loop(Socket, Transport); _ -> ok = Transport:close(Socket) end.
Special processes like the ones that use the gen_statem
or gen_server
behaviours have the particularity of having their start_link
call not return until the init
function returns. This is problematic, because you won't be able to call ranch:handshake/1,2
from the init
callback as this would cause a deadlock to happen.
This problem can be addressed in several ways.
ranch:handshake/1,2
call in the enter clause of the initial state. Check the tcp_reverse
example for a complete example.
next_event
action in the return from init/1
and place the ranch:handshake/1,2
call in the clause handling the event in the initial state.
gen_statem:enter_loop/4
function and start your process with proc_lib:spawn_link/3
or proc_lib:start_link/3,4,5
. See below for an example.
-module(my_protocol). -behaviour(gen_statem). -behaviour(ranch_protocol). -export([start_link/3]). -export([init/1]). %% Exports of other gen_statem callbacks here. start_link(Ref, Transport, Opts) -> {ok, proc_lib:spawn_link(?MODULE, init, [{Ref, Transport, Opts}])}. init({Ref, Transport, _Opts}) -> %% Perform any required state initialization here. {ok, Socket} = ranch:handshake(Ref), ok = Transport:setopts(Socket, [{active, once}]), gen_statem:enter_loop(?MODULE, [], state_name, {state_data, Socket, Transport}). %% Other gen_statem callbacks here.
{continue, Continue}
in the return from init/1
and place the ranch:handshake/1,2
call in a corresponding handle_continue/2
clause.
gen_server:enter_loop/3
function and start your process with proc_lib:spawn_link/3
or proc_lib:start_link/3,4,5
.
Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:
Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.