From 1e4e5ab4d2e1fb0d1d447c69be034e9c3377a329 Mon Sep 17 00:00:00 2001
From: Aurelien DARRAGON <adarragon@haproxy.com>
Date: Fri, 21 Mar 2025 09:37:38 +0100
Subject: [PATCH] MINOR: hlua: add core.wait()

Similar to core.yield(), except that the task is not woken up
automatically, instead it waits for events to trigger the task
wakeup.

Lua documentation was updated.
---
 doc/lua-api/index.rst | 11 ++++++++++-
 src/hlua.c            | 12 ++++++++++++
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/doc/lua-api/index.rst b/doc/lua-api/index.rst
index 456f915d4..267b9f42f 100644
--- a/doc/lua-api/index.rst
+++ b/doc/lua-api/index.rst
@@ -926,12 +926,21 @@ Core class
   its work and wants to give back the control to HAProxy without executing the
   remaining code. It can be seen as a multi-level "return".
 
+.. js:function:: core.wait()
+
+  **context**: task, action
+
+  Give back the hand at the HAProxy scheduler. Unlike :js:func:`core.yield`
+  the task will not be woken up automatically to resume as fast as possible.
+  Instead, it will wait for an event to wake the task.
+
 .. js:function:: core.yield()
 
   **context**: task, action
 
   Give back the hand at the HAProxy scheduler. It is used when the LUA
-  processing consumes a lot of processing time.
+  processing consumes a lot of processing time. Lua excecution will be resumed
+  automatically (automatic reschedule).
 
 .. js:function:: core.parse_addr(address)
 
diff --git a/src/hlua.c b/src/hlua.c
index bc260f44e..ac253361b 100644
--- a/src/hlua.c
+++ b/src/hlua.c
@@ -9247,6 +9247,17 @@ __LJMP static int hlua_yield(lua_State *L)
 	return 0;
 }
 
+/* same as hlua_yield() but doesn't enforce CTRLYIELD so the Lua task won't be
+ * automatically woken up to resume ASAP, instead it means we will wait for
+ * an event to occur to wake the task. Only use when you're confident that
+ * something or someone will wake the task at some point.
+ */
+__LJMP static int hlua_wait(lua_State *L)
+{
+	MAY_LJMP(hlua_yieldk(L, 0, 0, hlua_yield_yield, TICK_ETERNITY, 0));
+	return 0;
+}
+
 /* This function change the nice of the currently executed
  * task. It is used set low or high priority at the current
  * task.
@@ -13877,6 +13888,7 @@ lua_State *hlua_init_state(int thread_num)
 	hlua_class_function(L, "register_cli", hlua_register_cli);
 	hlua_class_function(L, "register_filter", hlua_register_filter);
 	hlua_class_function(L, "yield", hlua_yield);
+	hlua_class_function(L, "wait", hlua_wait);
 	hlua_class_function(L, "set_nice", hlua_set_nice);
 	hlua_class_function(L, "sleep", hlua_sleep);
 	hlua_class_function(L, "msleep", hlua_msleep);