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/1.5/guide/protocols/index.html | 248 --------------------------- 1 file changed, 248 deletions(-) delete mode 100644 docs/en/ranch/1.5/guide/protocols/index.html (limited to 'docs/en/ranch/1.5/guide/protocols') diff --git a/docs/en/ranch/1.5/guide/protocols/index.html b/docs/en/ranch/1.5/guide/protocols/index.html deleted file mode 100644 index dcba343e..00000000 --- a/docs/en/ranch/1.5/guide/protocols/index.html +++ /dev/null @@ -1,248 +0,0 @@ - - - - - - - - - - Nine Nines: Protocols - - - - - - - - - - - - - - -

- - - -

- -

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/4. This callback is responsible for spawning a new process for handling the connection. It receives four arguments: the name of the listener, the socket, 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:accept_ack/1 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.

Acknowledge accepting the socket

ok = ranch:accept_ack(Ref).

If your protocol code requires specific socket options, you should set them while initializing your connection process, after calling ranch:accept_ack/1. 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/4]).
--export([init/4]).
-
-start_link(Ref, Socket, Transport, Opts) ->
-	Pid = spawn_link(?MODULE, init, [Ref, Socket, Transport, Opts]),
-	{ok, Pid}.
-
-init(Ref, Socket, Transport, _Opts = []) ->
-	ok = ranch:accept_ack(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_server

Special processes like the ones that use the gen_server or gen_fsm 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:accept_ack/1 from the init callback as this would cause a deadlock to happen.

Use the gen_server:enter_loop/3 function. It allows you to start your process normally (although it must be started with proc_lib like all special processes), then perform any needed operations before falling back into the normal gen_server execution loop.

Use a gen_server for protocol handling

-module(my_protocol).
--behaviour(gen_server).
--behaviour(ranch_protocol).
-
--export([start_link/4]).
--export([init/1]).
-%% Exports of other gen_server callbacks here.
-
-start_link(Ref, Socket, Transport, Opts) ->
-	{ok, proc_lib:spawn_link(?MODULE, init, [{Ref, Socket, Transport, Opts}])}.
-
-init({Ref, Socket, Transport, _Opts = []}) ->
-	%% Perform any required state initialization here.
-	ok = ranch:accept_ack(Ref),
-	ok = Transport:setopts(Socket, [{active, once}]),
-	gen_server:enter_loop(?MODULE, [], {state, Socket, Transport}).
-
-%% Other gen_server callbacks here.

Check the tcp_reverse example for a complete example.

- - - - - - - - - - - - - - - - -

- -

- - -

- Ranch - 1.5 - - User Guide -

- -

User Guide
Function Reference

- -

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