Browse Source

Remove bad advice for gen_server protocols

Also improves the good example a little by using spawn_link
instead of start_link.
Loïc Hoguin 8 years ago
parent
commit
2c93d8ef43
2 changed files with 7 additions and 37 deletions
  1. 4 32
      doc/src/guide/protocols.asciidoc
  2. 3 5
      examples/tcp_reverse/src/reverse_protocol.erl

+ 4 - 32
doc/src/guide/protocols.asciidoc

@@ -67,10 +67,7 @@ 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.
 
-There are two ways of solving this problem.
-
-The first, and probably the most elegant one, is to make use of the
-`gen_server:enter_loop/3` function. It allows you to start your process
+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.
@@ -84,14 +81,13 @@ the normal `gen_server` execution loop.
 -behaviour(ranch_protocol).
 
 -export([start_link/4]).
--export([init/4]).
+-export([init/1]).
 %% Exports of other gen_server callbacks here.
 
 start_link(Ref, Socket, Transport, Opts) ->
-	proc_lib:start_link(?MODULE, init, [Ref, Socket, Transport, Opts]).
+	{ok, proc_lib:spawn_link(?MODULE, init, [{Ref, Socket, Transport, Opts}])}.
 
-init(Ref, Socket, Transport, _Opts = []) ->
-	ok = proc_lib:init_ack({ok, self()}),
+init({Ref, Socket, Transport, _Opts = []}) ->
 	%% Perform any required state initialization here.
 	ok = ranch:accept_ack(Ref),
 	ok = Transport:setopts(Socket, [{active, once}]),
@@ -99,27 +95,3 @@ init(Ref, Socket, Transport, _Opts = []) ->
 
 %% Other gen_server callbacks here.
 ----
-
-The second method involves triggering a timeout just after `gen_server:init`
-ends. If you return a timeout value of `0` then the `gen_server` will call
-`handle_info(timeout, _, _)` right away.
-
-.Use a gen_server for protocol handling, method 2
-
-[source,erlang]
-----
--module(my_protocol).
--behaviour(gen_server).
--behaviour(ranch_protocol).
-
-%% Exports go here.
-
-init([Ref, Socket, Transport]) ->
-	{ok, {state, Ref, Socket, Transport}, 0}.
-
-handle_info(timeout, State={state, Ref, Socket, Transport}) ->
-	ok = ranch:accept_ack(Ref),
-	ok = Transport:setopts(Socket, [{active, once}]),
-	{noreply, State};
-%% ...
-----

+ 3 - 5
examples/tcp_reverse/src/reverse_protocol.erl

@@ -9,7 +9,6 @@
 
 %% gen_server.
 -export([init/1]).
--export([init/4]).
 -export([handle_call/3]).
 -export([handle_cast/2]).
 -export([handle_info/2]).
@@ -23,16 +22,15 @@
 %% API.
 
 start_link(Ref, Socket, Transport, Opts) ->
-	proc_lib:start_link(?MODULE, init, [Ref, Socket, Transport, Opts]).
+	{ok, proc_lib:spawn_link(?MODULE, init, [{Ref, Socket, Transport, Opts}])}.
 
 %% gen_server.
 
 %% This function is never called. We only define it so that
 %% we can use the -behaviour(gen_server) attribute.
-init([]) -> {ok, undefined}.
+%init([]) -> {ok, undefined}.
 
-init(Ref, Socket, Transport, _Opts = []) ->
-	ok = proc_lib:init_ack({ok, self()}),
+init({Ref, Socket, Transport, _Opts = []}) ->
 	ok = ranch:accept_ack(Ref),
 	ok = Transport:setopts(Socket, [{active, once}]),
 	gen_server:enter_loop(?MODULE, [],