LUA record documentation (version number, shared model)

Co-Authored-By: Frank Louwers <24672+franklouwers@users.noreply.github.com>

diff --git a/docs/lua-records/index.rst b/docs/lua-records/index.rst
index d44dbe1a0b03bd8043b921acd45b4db39d114be2..6f23cfed173bfabb7fe8730f50a6ffb8c04778b7 100644 (file)
--- a/docs/lua-records/index.rst
+++ b/docs/lua-records/index.rst
@@ -197,6 +197,20 @@ Note that to protect operators, support for LUA records must be enabled
 explicitly, either globally (``enable-lua-records``) or per zone
 (``ENABLE-LUA-RECORDS`` = 1).
 
+.. _lua-records-shared-state:
+
+Shared Lua state model
+----------------------
+
+The default mode of operation for LUA records is to create a fresh Lua state for every query that hits a LUA record.
+This way, different LUA records cannot accidentally interfere with each other, by leaving around global objects, or perhaps even deleting relevant functions.
+However, creating a Lua state (and registering all our functions for it, see Reference below) takes measurable time.
+For users that are confident they can write Lua scripts that will not interfere with eachother, a mode is supported where Lua states are created on the first query, and then reused forever.
+In non-scientific testing this has yielded up to 10x QPS increases.
+
+To use this mode, set ``enable-lua-records=shared``.
+Note that this enables LUA records for all zones.
+
 Reference
 ---------
 

diff --git a/docs/settings.rst b/docs/settings.rst
index 50fa520f03511a54d9ae1aaa6932dbccea86382f..26417a60364b90a0ae717fed0c3299aa7076abf2 100644 (file)
--- a/docs/settings.rst
+++ b/docs/settings.rst
@@ -593,10 +593,14 @@ Enables EDNS subnet processing, for backends that support it.
 ``enable-lua-records``
 ----------------------
 
--  Boolean
+-  One of ``no``, ``yes`` (or empty), or ``shared``, String
 -  Default: no
 
-Enable globally the LUA records feature
+.. versionadded:: 4.2.0
+
+Globally enable the :doc:`LUA records <lua-records/index>` feature.
+
+To use shared LUA states, set this to ``shared``, see :ref:`lua-records-shared-state`.
 
 .. _setting-entropy-source: