From 5ada450fe10a5fc51b7f3f0900571a10547635a1 Mon Sep 17 00:00:00 2001
From: "j.uhlig" <j.uhlig@mailingwork.de>
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

