From 390bbd4f3b5d62ff635f2b9ffb9572f00112638a Mon Sep 17 00:00:00 2001
From: BlackMATov <blackmat@mail.ru>
Date: Sat, 23 Nov 2024 10:52:30 +0700
Subject: [PATCH] evolved.id alias

---
 README.md           | 10 +++++-----
 evolved/idpools.lua | 36 +++++++++++++++++++-----------------
 2 files changed, 24 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index f9e1dcb..cc09116 100644
--- a/README.md
+++ b/README.md
@@ -6,11 +6,11 @@
 
 ```
 idpools.idpool -> (idpool)
-idpools.pack -> integer -> integer -> (integer)
-idpools.unpack -> integer -> (integer, integer)
-idpools.acquire -> idpool -> (integer)
-idpools.release -> idpool -> integer -> ()
-idpools.is_alive -> idpool -> integer -> (boolean)
+idpools.pack -> integer -> integer -> (id)
+idpools.unpack -> id -> (integer, integer)
+idpools.acquire -> idpool -> (id)
+idpools.release -> idpool -> id -> ()
+idpools.is_alive -> idpool -> id -> (boolean)
 ```
 
 ### Module `registry`
diff --git a/evolved/idpools.lua b/evolved/idpools.lua
index 39af2ec..e727ee3 100644
--- a/evolved/idpools.lua
+++ b/evolved/idpools.lua
@@ -1,8 +1,10 @@
 ---@class evolved.idpools
 local idpools = {}
 
+---@alias evolved.id integer
+
 ---@class evolved.idpool
----@field package __acquired_ids integer[]
+---@field package __freelist_ids evolved.id[]
 ---@field package __available_index integer
 local evolved_idpool_mt = {}
 evolved_idpool_mt.__index = evolved_idpool_mt
@@ -11,7 +13,7 @@ evolved_idpool_mt.__index = evolved_idpool_mt
 function idpools.idpool()
     ---@type evolved.idpool
     local idpool = {
-        __acquired_ids = {},
+        __freelist_ids = {},
         __available_index = 0,
     }
     return setmetatable(idpool, evolved_idpool_mt)
@@ -19,14 +21,14 @@ end
 
 ---@param index integer
 ---@param version integer
----@return integer
+---@return evolved.id
 function idpools.pack(index, version)
     assert(index >= 1 and index <= 0xFFFFF, 'id index out of range [1;0xFFFFF]')
     assert(version >= 1 and version <= 0x7FF, 'id version out of range [1;0x7FF]')
     return index + version * 0x100000
 end
 
----@param id integer
+---@param id evolved.id
 ---@return integer index
 ---@return integer version
 function idpools.unpack(id)
@@ -36,39 +38,39 @@ function idpools.unpack(id)
 end
 
 ---@param idpool evolved.idpool
----@return integer
+---@return evolved.id
 ---@nodiscard
 function idpools.acquire(idpool)
     if idpool.__available_index ~= 0 then
         local index = idpool.__available_index
-        local available_id = idpool.__acquired_ids[index]
-        idpool.__available_index = available_id % 0x100000
-        local version = available_id - idpool.__available_index
+        local freelist_id = idpool.__freelist_ids[index]
+        idpool.__available_index = freelist_id % 0x100000
+        local version = freelist_id - idpool.__available_index
 
         local acquired_id = index + version
-        idpool.__acquired_ids[index] = acquired_id
+        idpool.__freelist_ids[index] = acquired_id
         return acquired_id
     else
-        if #idpool.__acquired_ids == 0xFFFFF then
+        if #idpool.__freelist_ids == 0xFFFFF then
             error('id index overflow', 2)
         end
 
-        local index = #idpool.__acquired_ids + 1
+        local index = #idpool.__freelist_ids + 1
         local version = 0x100000
 
         local acquired_id = index + version
-        idpool.__acquired_ids[index] = acquired_id
+        idpool.__freelist_ids[index] = acquired_id
         return acquired_id
     end
 end
 
 ---@param idpool evolved.idpool
----@param id integer
+---@param id evolved.id
 function idpools.release(idpool, id)
     local index = id % 0x100000
     local version = id - index
 
-    if idpool.__acquired_ids[index] ~= id then
+    if idpool.__freelist_ids[index] ~= id then
         error('id is not acquired or already released', 2)
     end
 
@@ -76,17 +78,17 @@ function idpools.release(idpool, id)
         and 0x100000
         or version + 0x100000
 
-    idpool.__acquired_ids[index] = idpool.__available_index + version
+    idpool.__freelist_ids[index] = idpool.__available_index + version
     idpool.__available_index = index
 end
 
 ---@param idpool evolved.idpool
----@param id integer
+---@param id evolved.id
 ---@return boolean
 ---@nodiscard
 function idpools.is_alive(idpool, id)
     local index = id % 0x100000
-    return idpool.__acquired_ids[index] == id
+    return idpool.__freelist_ids[index] == id
 end
 
 return idpools