From a81dc8af9db314e074512e7fc096978c64c9bed1 Mon Sep 17 00:00:00 2001
From: jdamanalo <jamanalo5@up.edu.ph>
Date: Thu, 9 Mar 2023 15:54:41 +0800
Subject: Add timeout to cowboy_loop

LH: I have added a test that does both hibernate and timeout
    and fixed a related issue. I also tweaked the docs and tests.
---
 doc/src/guide/loop_handlers.asciidoc | 27 ++++++++++++++++++++++++++-
 doc/src/manual/cowboy_loop.asciidoc  |  8 +++++---
 2 files changed, 31 insertions(+), 4 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/guide/loop_handlers.asciidoc b/doc/src/guide/loop_handlers.asciidoc
index e574854..fc45d1c 100644
--- a/doc/src/guide/loop_handlers.asciidoc
+++ b/doc/src/guide/loop_handlers.asciidoc
@@ -31,7 +31,10 @@ for plain HTTP handlers.
 The `init/2` function must return a `cowboy_loop` tuple to enable
 loop handler behavior. This tuple may optionally contain
 the atom `hibernate` to make the process enter hibernation
-until a message is received.
+until a message is received. Alternatively, the tuple may
+optionally contain a positive integer to create a `timeout`
+message when the process has not received messages for too
+long.
 
 This snippet enables the loop handler:
 
@@ -49,6 +52,14 @@ init(Req, State) ->
     {cowboy_loop, Req, State, hibernate}.
 ----
 
+This makes the process time out after 1000ms of idle time.
+
+[source,erlang]
+----
+init(Req, State) ->
+    {cowboy_loop, Req, State, 1000}.
+----
+
 === Receive loop
 
 Once initialized, Cowboy will wait for messages to arrive
@@ -123,3 +134,17 @@ messages received. This is done by returning the atom
 `hibernate` as part of the `loop` tuple callbacks normally
 return. Just add the atom at the end and Cowboy will hibernate
 accordingly.
+
+=== Idle timeout
+
+You may activate timeout events by returning a positive integer
+`N` as part of the `loop` tuple callbacks return. The default
+value is `infinity`. The `info` callback will be called with the
+atom `timeout` unless a message is received within `N` milliseconds:
+
+[source,erlang]
+----
+info(timeout, Req, State) ->
+    %% Do something...
+    {ok, Req, State, 1000}.
+----
diff --git a/doc/src/manual/cowboy_loop.asciidoc b/doc/src/manual/cowboy_loop.asciidoc
index 000149d..8c9a816 100644
--- a/doc/src/manual/cowboy_loop.asciidoc
+++ b/doc/src/manual/cowboy_loop.asciidoc
@@ -28,11 +28,11 @@ Loop handlers implement the following interface:
 ----
 init(Req, State)
     -> {cowboy_loop, Req, State}
-     | {cowboy_loop, Req, State, hibernate}
+     | {cowboy_loop, Req, State, hibernate | timeout()}
 
 info(Info, Req, State)
     -> {ok, Req, State}
-     | {ok, Req, State, hibernate}
+     | {ok, Req, State, hibernate | timeout()}
      | {stop, Req, State}
 
 terminate(Reason, Req, State) -> ok  %% optional
@@ -69,7 +69,9 @@ stop::
 
 == Changelog
 
-* *2.0*: Loop handlers no longer need to handle overflow/timeouts.
+* *2.11*: A timeout may be returned instead of `hibernate`.
+          It functions the same way as the `gen_server` timeout.
+* *2.0*: Loop handlers no longer need to handle socket events.
 * *1.0*: Behavior introduced.
 
 == See also
-- 
cgit v1.2.3