DOC: lua: fix yield-dependent methods expected contexts
authorAurelien DARRAGON <adarragon@haproxy.com>
Tue, 19 Nov 2024 18:28:16 +0000 (19:28 +0100)
committerChristopher Faulet <cfaulet@haproxy.com>
Fri, 22 Nov 2024 14:44:48 +0000 (15:44 +0100)
Contrary to what the doc states, it is not expected (nor relevant) to
use yield-dependent methods such as core.yield() or core.(m)sleep() from
contexts that don't support yielding. Such contexts include body, init,
fetches and converters.

Thus the doc got it wrong since the beginning, because such methods were
never supported from the above contexts, yet it was listed in the list
of compatible contexts (probably the result of a copy-paste), which is
error-prone because it could either cause a Lua runtime error to be
thrown, or be ignored in some other cases.

It should be backported to all stable versions.

(cherry picked from commit 501827ebe0ad8f4121c4397267afbc7968e3d9af)
Signed-off-by: Christopher Faulet <cfaulet@haproxy.com>

doc/lua-api/index.rst

index cfef26c..b335a0d 100644 (file)
@@ -485,7 +485,7 @@ Core class
 
 .. js:function:: core.msleep(milliseconds)
 
-  **context**: body, init, task, action
+  **context**: task, action
 
   The `core.msleep()` stops the Lua execution between specified milliseconds.
 
@@ -841,7 +841,7 @@ Core class
 
 .. js:function:: core.sleep(int seconds)
 
-  **context**: body, init, task, action
+  **context**: task, action
 
   The `core.sleep()` functions stop the Lua execution between specified seconds.
 
@@ -894,7 +894,7 @@ Core class
 
 .. js:function:: core.yield()
 
-  **context**: task, action, sample-fetch, converter
+  **context**: task, action
 
   Give back the hand at the HAProxy scheduler. It is used when the LUA
   processing consumes a lot of processing time.