From 5ada450fe10a5fc51b7f3f0900571a10547635a1 Mon Sep 17 00:00:00 2001 From: "j.uhlig" Date: Tue, 26 Jun 2018 17:07:13 +0200 Subject: Introduce Transport:handshake/1,2 This commit deprecates Transport:accept_ack/1 in favor of a new forward-compatible function. Transport:handshake/1,2 will use ssl:handshake/2,3 from Ranch 2.0 onward. --- doc/src/guide/protocols.asciidoc | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) (limited to 'doc/src/guide/protocols.asciidoc') diff --git a/doc/src/guide/protocols.asciidoc b/doc/src/guide/protocols.asciidoc index 91f4b07..b20b22d 100644 --- a/doc/src/guide/protocols.asciidoc +++ b/doc/src/guide/protocols.asciidoc @@ -14,18 +14,18 @@ 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. +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. -.Acknowledge accepting the socket +.Perform the socket handshake [source,erlang] -ok = ranch:accept_ack(Ref). +{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:accept_ack/1`. You can use `Transport:setopts/2` +calling `ranch:handshake/{1,2}`. You can use `Transport:setopts/2` for that purpose. Following is the complete protocol code for the example found @@ -39,14 +39,14 @@ in `examples/tcp_echo/`. -behaviour(ranch_protocol). -export([start_link/4]). --export([init/4]). +-export([init/3]). -start_link(Ref, Socket, Transport, Opts) -> - Pid = spawn_link(?MODULE, init, [Ref, Socket, Transport, Opts]), +start_link(Ref, _Socket, Transport, Opts) -> + Pid = spawn_link(?MODULE, init, [Ref, Transport, Opts]), {ok, Pid}. -init(Ref, Socket, Transport, _Opts = []) -> - ok = ranch:accept_ack(Ref), +init(Ref, Transport, _Opts = []) -> + {ok, Socket} = ranch:handshake(Ref), loop(Socket, Transport). loop(Socket, Transport) -> @@ -64,7 +64,7 @@ loop(Socket, Transport) -> 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:accept_ack/1` from the `init` callback +you won't be able to call `ranch:handshake/{1,2}` from the `init` callback as this would cause a deadlock to happen. Use the `gen_statem:enter_loop/4` function. It allows you to start your process @@ -84,12 +84,12 @@ the normal `gen_statem` execution loop. -export([init/1]). %% Exports of other gen_statem callbacks here. -start_link(Ref, Socket, Transport, Opts) -> - {ok, proc_lib:spawn_link(?MODULE, init, [{Ref, Socket, Transport, Opts}])}. +start_link(Ref, _Socket, Transport, Opts) -> + {ok, proc_lib:spawn_link(?MODULE, init, [{Ref, Transport, Opts}])}. -init({Ref, Socket, Transport, _Opts = []}) -> +init({Ref, Transport, _Opts = []}) -> %% Perform any required state initialization here. - ok = ranch:accept_ack(Ref), + {ok, Socket} = ranch:handshake(Ref), ok = Transport:setopts(Socket, [{active, once}]), gen_statem:enter_loop(?MODULE, [], state_name, {state_data, Socket, Transport}). -- cgit v1.2.3