From 992831c7a516b5183c2af06260829d41aa45267c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Thu, 9 Sep 2021 12:15:32 +0200 Subject: Ranch 2.1.0 --- docs/en/ranch/2.1/guide/protocols/index.html | 261 +++++++++++++++++++++++++++ 1 file changed, 261 insertions(+) create mode 100644 docs/en/ranch/2.1/guide/protocols/index.html (limited to 'docs/en/ranch/2.1/guide/protocols/index.html') diff --git a/docs/en/ranch/2.1/guide/protocols/index.html b/docs/en/ranch/2.1/guide/protocols/index.html new file mode 100644 index 00000000..d275248c --- /dev/null +++ b/docs/en/ranch/2.1/guide/protocols/index.html @@ -0,0 +1,261 @@ + + + + + + + + + + Nine Nines: Protocols + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Protocols

+ +

A protocol handler starts a connection process and defines the protocol logic executed in this process.

+

Writing a protocol handler

+

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.

+
Perform the socket handshake
+
+
{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/.

+
Protocol module that echoes everything it receives
+
+
-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.
+
+

Using gen_statem and gen_server

+

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.

+

gen_statem

+
  • Use state enter calls and place the ranch:handshake/1,2 call in the enter clause of the initial state. Check the tcp_reverse example for a complete example. +
    • +
  • Use a 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. +
    • +
  • Use the 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. +
    • +
+
Using gen_statem:enter_loop/4 to start a protocol
+
+
-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.
+
+

gen_server

+
  • Use {continue, Continue} in the return from init/1 and place the ranch:handshake/1,2 call in a corresponding handle_continue/2 clause. +
    • +
  • Use the gen_server:enter_loop/3 function and start your process with proc_lib:spawn_link/3 or proc_lib:start_link/3,4,5. +
    • +
+ + + + + + + + + + + + + + + + +
+ +
+ + +

+ Ranch + 2.1 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

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.

+ + + +
+
+
+
+ + + + + + + + + -- cgit v1.2.3