Allow websocket handlers to hibernate from the websocket_init/3 function

Also improve the documentation about hibernate.

src/cowboy_http_websocket.erl

@@ -116,9 +116,15 @@ handler_init(State=#state{handler=Handler, opts=Opts},
 	try Handler:websocket_init(Transport:name(), Req, Opts) of
 		{ok, Req2, HandlerState} ->
 			websocket_handshake(State, Req2, HandlerState);
+		{ok, Req2, HandlerState, hibernate} ->
+			websocket_handshake(State#state{hibernate=true},
+				Req2, HandlerState);
 		{ok, Req2, HandlerState, Timeout} ->
 			websocket_handshake(State#state{timeout=Timeout},
-				Req2, HandlerState)
+				Req2, HandlerState);
+		{ok, Req2, HandlerState, Timeout, hibernate} ->
+			websocket_handshake(State#state{timeout=Timeout,
+				hibernate=true}, Req2, HandlerState)
 	catch Class:Reason ->
 		upgrade_error(Req),
 		error_logger:error_msg(

src/cowboy_http_websocket_handler.erl

@@ -29,8 +29,7 @@
 %% here.
 %%
 %% <em>websocket_handle/3</em> receives the data from the socket. It can reply
-%% something, do nothing or close the connection. You can choose to hibernate
+%% something, do nothing or close the connection.
-%% the process by returning <em>hibernate</em> to save memory and CPU.
 %%
 %% <em>websocket_info/3</em> receives messages sent to the process. It has
 %% the same reply format as <em>websocket_handle/3</em> described above. Note
@@ -41,6 +40,11 @@
 %% <em>websocket_terminate/3</em> is meant for cleaning up. It also receives
 %% the request and the state previously defined, along with a reason for
 %% termination.
+%%
+%% All of <em>websocket_init/3</em>, <em>websocket_handle/3</em> and
+%% <em>websocket_info/3</em> can decide to hibernate the process by adding
+%% an extra element to the returned tuple, containing the atom
+%% <em>hibernate</em>. Doing so helps save memory and improve CPU usage.
 -module(cowboy_http_websocket_handler).
 
 -export([behaviour_info/1]).