Add cowboy:accept_ack/1 for a cleaner handling of the shoot message

README.md

@@ -244,9 +244,10 @@ is the pid to the listener's gen_server, managing the connections. Socket is of
 course the client socket; Transport is the module name of the chosen transport
 handler and Opts is protocol options defined when starting the listener.
 
-After initializing your protocol, it is recommended to wait to receive a message
-containing the atom 'shoot', as it will ensure Cowboy has been able to fully
-initialize the socket. Anything you do past this point is up to you!
+After initializing your protocol, it is recommended to call the
+function cowboy:accept_ack/1 with the ListenerPid as argument,
+as it will ensure Cowboy has been able to fully initialize the socket.
+Anything you do past this point is up to you!
 
 If you need to change some socket options, like enabling raw mode for example,
 you can call the <em>Transport:setopts/2</em> function. It is the protocol's

src/cowboy.erl

@@ -15,7 +15,7 @@
 %% @doc Cowboy API to start and stop listeners.
 -module(cowboy).
 
--export([start_listener/6, stop_listener/1, child_spec/6]).
+-export([start_listener/6, stop_listener/1, child_spec/6, accept_ack/1]).
 
 %% @doc Start a listener for the given transport and protocol.
 %%
@@ -61,6 +61,7 @@ stop_listener(Ref) ->
 	end.
 
 %% @doc Return a child spec suitable for embedding.
+%%
 %% When you want to embed cowboy in another application, you can use this
 %% function to create a <em>ChildSpec</em> suitable for use in a supervisor.
 %% The parameters are the same as in <em>start_listener/6</em> but rather
@@ -74,3 +75,11 @@ child_spec(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts)
 	{{cowboy_listener_sup, Ref}, {cowboy_listener_sup, start_link, [
 		NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts
 	]}, permanent, 5000, supervisor, [cowboy_listener_sup]}.
+
+%% @doc Acknowledge the accepted connection.
+%%
+%% Effectively used to make sure the socket control has been given to
+%% the protocol process before starting to use it.
+-spec accept_ack(pid()) -> ok.
+accept_ack(ListenerPid) ->
+	receive {shoot, ListenerPid} -> ok end.

src/cowboy_acceptor.erl

@@ -40,7 +40,7 @@ acceptor(LSocket, Transport, Protocol, Opts, MaxConns, ListenerPid, ReqsSup) ->
 			Transport:controlling_process(CSocket, Pid),
 			{ok, NbConns} = cowboy_listener:add_connection(ListenerPid,
 				default, Pid),
-			Pid ! shoot,
+			Pid ! {shoot, ListenerPid},
 			limit_reqs(ListenerPid, NbConns, MaxConns);
 		{error, timeout} ->
 			ignore;

src/cowboy_http_protocol.erl

@@ -77,7 +77,7 @@ init(ListenerPid, Socket, Transport, Opts) ->
 	Timeout = proplists:get_value(timeout, Opts, 5000),
 	URLDecDefault = {fun cowboy_http:urldecode/2, crash},
 	URLDec = proplists:get_value(urldecode, Opts, URLDecDefault),
-	receive shoot -> ok end,
+	ok = cowboy:accept_ack(ListenerPid),
 	wait_request(#state{listener=ListenerPid, socket=Socket, transport=Transport,
 		dispatch=Dispatch, max_empty_lines=MaxEmptyLines,
 		max_line_length=MaxLineLength, timeout=Timeout, urldecode=URLDec}).

src/cowboy_protocol.erl

@@ -24,9 +24,9 @@
 %% starting the listener. The <em>start_link/4</em> function must follow
 %% the supervisor start function specification.
 %%
-%% After initializing your protocol, it is recommended to wait to
-%% receive a message containing the atom 'shoot', as it will ensure
-%% Cowboy has been able to fully initialize the socket.
+%% After initializing your protocol, it is recommended to call the
+%% function cowboy:accept_ack/1 with the ListenerPid as argument,
+%% as it will ensure Cowboy has been able to fully initialize the socket.
 %% Anything you do past this point is up to you!
 %%
 %% If you need to change some socket options, like enabling raw mode