chore: update table.* and tablepool annotations

7 files changed, 135 insertions, 7 deletions

diff --git a/meta/3rd/OpenResty/library/table.clear.lua b/meta/3rd/OpenResty/library/table.clear.lua
index 85838ea8..ba6dfa24 100644
--- a/meta/3rd/OpenResty/library/table.clear.lua
+++ b/meta/3rd/OpenResty/library/table.clear.lua
@@ -1,3 +1,7 @@
 ---@meta
-function table_clear() end
-return table_clear
\ No newline at end of file
+
+--- Clear a table of its contents.
+---@param t table
+local function clear(t) end
+
+return clear
\ No newline at end of file
diff --git a/meta/3rd/OpenResty/library/table.clone.lua b/meta/3rd/OpenResty/library/table.clone.lua
new file mode 100644
index 00000000..ff2ce870
--- /dev/null
+++ b/meta/3rd/OpenResty/library/table.clone.lua
@@ -0,0 +1,25 @@
+---@meta
+
+--- Returns a shallow copy of the given Lua table.
+---
+--- This API can be JIT compiled.
+---
+--- Usage:
+---
+--- ```lua
+--- local clone = require "table.clone"
+---
+--- local x = {x=12, y={5, 6, 7}}
+--- local y = clone(x)
+--- ```
+---
+--- **Note:** We observe 7% over-all speedup in the edgelang-fan compiler's
+--- compiling speed whose Lua is generated by the fanlang compiler.
+---
+--- **Note bis:** Deep cloning is planned to be supported by adding `true` as a second argument.
+---
+---@param t table
+---@return table
+local function clone(t) end
+
+return clone
diff --git a/meta/3rd/OpenResty/library/table.isarray.lua b/meta/3rd/OpenResty/library/table.isarray.lua
new file mode 100644
index 00000000..f2ee3c72
--- /dev/null
+++ b/meta/3rd/OpenResty/library/table.isarray.lua
@@ -0,0 +1,23 @@
+---@meta
+
+--- Returns `true` when the given Lua table is a pure array-like Lua table, or
+--- `false` otherwise.
+---
+--- Empty Lua tables are treated as arrays.
+---
+--- This API can be JIT compiled.
+---
+--- Usage:
+---
+--- ```lua
+--- local isarray = require "table.isarray"
+---
+--- print(isarray{"a", true, 3.14})  -- true
+--- print(isarray{dog = 3})  -- false
+--- print(isarray{})  -- true
+--- ```
+---@param t table
+---@return boolean
+local function isarray(t) end
+
+return isarray
diff --git a/meta/3rd/OpenResty/library/table.isempty.lua b/meta/3rd/OpenResty/library/table.isempty.lua
new file mode 100644
index 00000000..b1cef6fb
--- /dev/null
+++ b/meta/3rd/OpenResty/library/table.isempty.lua
@@ -0,0 +1,22 @@
+---@meta
+
+--- Returns `true` when the given Lua table contains neither non-nil array elements nor non-nil key-value pairs, or `false` otherwise.
+---
+--- This API can be JIT compiled.
+--- Usage:
+---
+--- ```lua
+--- local isempty = require "table.isempty"
+---
+--- print(isempty({}))  -- true
+--- print(isempty({nil, dog = nil}))  -- true
+--- print(isempty({"a", "b"}))  -- false
+--- print(isempty({nil, 3}))  -- false
+--- print(isempty({cat = 3}))  -- false
+--- ```
+---
+---@param t table
+---@return boolean
+local function isempty(t) end
+
+return isempty
diff --git a/meta/3rd/OpenResty/library/table.new.lua b/meta/3rd/OpenResty/library/table.new.lua
index 3f6ac131..385fa672 100644
--- a/meta/3rd/OpenResty/library/table.new.lua
+++ b/meta/3rd/OpenResty/library/table.new.lua
@@ -1,3 +1,10 @@
 ---@meta
-function table_new() end
-return table_new
\ No newline at end of file
+
+--- Create a new table.
+---
+---@param narr integer number of array-like items
+---@param nrec integer number of hash-like items
+---@return table
+local function new(narr, nrec) end
+
+return new
\ No newline at end of file
diff --git a/meta/3rd/OpenResty/library/table.nkeys.lua b/meta/3rd/OpenResty/library/table.nkeys.lua
new file mode 100644
index 00000000..41a42d6a
--- /dev/null
+++ b/meta/3rd/OpenResty/library/table.nkeys.lua
@@ -0,0 +1,23 @@
+---@meta
+
+--- Returns the total number of elements in a given Lua table (i.e. from both the
+--- array and hash parts combined).
+---
+--- This API can be JIT compiled.
+---
+--- Usage:
+---
+--- ```lua
+--- local nkeys = require "table.nkeys"
+---
+--- print(nkeys({}))  -- 0
+--- print(nkeys({ "a", nil, "b" }))  -- 2
+--- print(nkeys({ dog = 3, cat = 4, bird = nil }))  -- 2
+--- print(nkeys({ "a", dog = 3, cat = 4 }))  -- 3
+--- ```
+---
+---@param t table
+---@return integer
+local function nkeys(t) end
+
+return nkeys
diff --git a/meta/3rd/OpenResty/library/tablepool.lua b/meta/3rd/OpenResty/library/tablepool.lua
index 809a23e3..056d2716 100644
--- a/meta/3rd/OpenResty/library/tablepool.lua
+++ b/meta/3rd/OpenResty/library/tablepool.lua
@@ -1,5 +1,29 @@
 ---@meta
-tablepool={}
-function tablepool.release(tag, obj, noclear) end
-function tablepool.fetch(tag, narr, nrec) end
+local tablepool={}
+
+--- Releases the already used Lua table, `tb`, into the table pool named `pool_name`. If the specified table pool does not exist, create it right away.
+---
+--- The caller must *not* continue using the released Lua table, `tb`, after this call. Otherwise random data corruption is expected.
+---
+--- The optional `no_clear` parameter specifies whether to clear the contents in the Lua table `tb` before putting it into the pool. Defaults to `false`, that is, always clearing the Lua table.
+---
+--- If you always initialize all the elements in the Lua table and always use the exactly same number of elements in the Lua table, then you can set this argument to `true` to avoid the overhead of explicit table clearing.
+---
+--- According to the current implementation, for maximum 200 Lua tables can be cached in an individual pool. We may make this configurable in the future. If the specified table pool already exceeds its size limit, then the `tb` table is subject to garbage collection. This behavior is to avoid potential memory leak due to unbalanced `fetch` and `release` method calls.
+---
+---@param pool_name string
+---@param tb        table
+---@param no_clear  boolean
+function tablepool.release(pool_name, tb, no_clear) end
+
+--- Fetches a (free) Lua table from the table pool of the specified name `pool_name`.
+---
+--- If the pool does not exist or the pool is empty, simply create a Lua table whose array part has `narr` elements and whose hash table part has `nrec` elements.
+---
+---@param  pool_name string
+---@param  narr      number size of the array-like part of the table
+---@param  nrec      number size of the hash-like part of the table
+---@return table
+function tablepool.fetch(pool_name, narr, nrec) end
+
 return tablepool
\ No newline at end of file