BUG/MEDIUM: hlua: Fix receive API for TCP applets to properly handle shutdowns

An optional timeout was added to AppletTCP.receive() to interrupt calls after a
delay. It was mandatory to be able to implement interactive applets (like
trisdemo). However, this broke the API and it made impossible to differentiate
the shutdowns from the delays expirations. Indeed, in both cases, an empty
string was returned.

Because historically an empty string was used to notify a connection shutdown,
it should not be changed. So now, 'nil' value is returned when no data was
available before the delay expiration.

The new AppletTCP:try_receive() function was also affected. To fix it, instead
of stating there is no delay when a receive is tried, an expired delay is
set. Concretely TICK_ETERNITY was replaced by now_ms.

Finally, AppletTCP:getline() function is not concerned for now because there
is no way to interrupt it after some delay.

The documentation and trisdemo lua script were updated accordingly.

This patch depends on "BUG/MEDIUM: hlua: Properly detect shudowns for TCP
applets based on the new API". However, it is a 3.2-specific issue, so no
backport is needed.

doc/lua-api/index.rst

@@ -3916,21 +3916,25 @@ AppletTCP class
   *size* is missing, the function tries to read all the content of the stream
   until the end. An optional timeout may be specified in milliseconds. In this
   case the function will return no longer than this delay, with the amount of
-  available data (possibly none).
+  available data, or nil if there is no data. An empty string is returned if the
+  connection is closed.
 
   :param class_AppletTCP applet: An :ref:`applettcp_class`
   :param integer size: the required read size.
-  :returns: always return a string, the string can be empty if the connection is
+  :returns: return nil if the timeout has expired and no data was available but
-   closed.
+   can still be received. Otherwise, a string is returned, possibly an empty
+   string if the connection is closed.
 
 .. js:function:: AppletTCP.try_receive(applet)
 
   Reads available data from the TCP stream and returns immediately. Returns a
-  string containing read bytes that may possibly be empty if no bytes are
+  string containing read bytes or nil if no bytes are available at that time. An
-  available at that time.
+  empty string is returned if the connection is closed.
 
   :param class_AppletTCP applet: An :ref:`applettcp_class`
-  :returns: always return a string, the string can be empty.
+  :returns: return nil if no data was available but can still be
+   received. Otherwise, a string is returned, possibly an empty string if the
+   connection is closed.
 
 .. js:function:: AppletTCP.send(appletmsg)
 

examples/lua/trisdemo.lua

@@ -215,7 +215,7 @@ function handler(applet)
 
         local input = applet:receive(1, delay)
         if input then
-            if input == "q" then
+            if input == "" or input == "q" then
                 game_over = true
             elseif input == "\27" then
                 local a = applet:receive(1, delay)

src/hlua.c

@@ -5405,7 +5405,7 @@ __LJMP static int hlua_applet_tcp_recv_try(lua_State *L)
 	if (ret == 0) {
 		if (tick_is_expired(exp_date, now_ms)) {
 			/* return the result. */
-			luaL_pushresult(&luactx->b);
+			lua_pushnil(L);
 			return 1;
 		}
 
@@ -5545,7 +5545,7 @@ __LJMP static int hlua_applet_tcp_try_recv(lua_State *L)
 	lua_pushinteger(L, -1);
 
 	/* set the expiration date (mandatory arg but not relevant here) */
-	lua_pushinteger(L, TICK_ETERNITY);
+	lua_pushinteger(L, now_ms);
 
 	/* Initialise the string catenation. */
 	luaL_buffinit(L, &luactx->b);