api reference for idpools module

README.md

@@ -2,6 +2,17 @@
 
 ## API Reference
 
+### Module `idpools`
+
+```
+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)
+```
+
 ### Module `registry`
 
 ```

develop/untests/idpools_untests.lua

@@ -10,19 +10,19 @@ end
 do
     local p = evo.idpools.idpool()
 
-    local i1_1 = evo.idpools.acquire_id(p)
+    local i1_1 = evo.idpools.acquire(p)
     assert(i1_1 == 0x100001)
 
-    local i2_1 = evo.idpools.acquire_id(p)
+    local i2_1 = evo.idpools.acquire(p)
     assert(i2_1 == 0x100002)
 
     do
-        local i, v = evo.idpools.unpack_id(i1_1)
+        local i, v = evo.idpools.unpack(i1_1)
         assert(i == 1 and v == 1)
     end
 
     do
-        local i, v = evo.idpools.unpack_id(i2_1)
+        local i, v = evo.idpools.unpack(i2_1)
         assert(i == 2 and v == 1)
     end
 end
@@ -30,42 +30,42 @@ end
 do
     local p = evo.idpools.idpool()
 
-    local i1_1 = evo.idpools.acquire_id(p)
-    local i2_1 = evo.idpools.acquire_id(p)
-    assert(evo.idpools.is_id_alive(p, i1_1))
-    assert(evo.idpools.is_id_alive(p, i2_1))
+    local i1_1 = evo.idpools.acquire(p)
+    local i2_1 = evo.idpools.acquire(p)
+    assert(evo.idpools.is_alive(p, i1_1))
+    assert(evo.idpools.is_alive(p, i2_1))
 
-    evo.idpools.release_id(p, i1_1)
-    assert(not evo.idpools.is_id_alive(p, i1_1))
-    assert(evo.idpools.is_id_alive(p, i2_1))
+    evo.idpools.release(p, i1_1)
+    assert(not evo.idpools.is_alive(p, i1_1))
+    assert(evo.idpools.is_alive(p, i2_1))
 
-    evo.idpools.release_id(p, i2_1)
-    assert(not evo.idpools.is_id_alive(p, i1_1))
-    assert(not evo.idpools.is_id_alive(p, i2_1))
+    evo.idpools.release(p, i2_1)
+    assert(not evo.idpools.is_alive(p, i1_1))
+    assert(not evo.idpools.is_alive(p, i2_1))
 
-    local i2_2 = evo.idpools.acquire_id(p)
+    local i2_2 = evo.idpools.acquire(p)
     assert(i2_2 == 0x200002)
 
-    local i1_2 = evo.idpools.acquire_id(p)
+    local i1_2 = evo.idpools.acquire(p)
     assert(i1_2 == 0x200001)
 
-    assert(not evo.idpools.is_id_alive(p, i1_1))
-    assert(not evo.idpools.is_id_alive(p, i2_1))
-    assert(evo.idpools.is_id_alive(p, i1_2))
-    assert(evo.idpools.is_id_alive(p, i2_2))
+    assert(not evo.idpools.is_alive(p, i1_1))
+    assert(not evo.idpools.is_alive(p, i2_1))
+    assert(evo.idpools.is_alive(p, i1_2))
+    assert(evo.idpools.is_alive(p, i2_2))
 end
 
 do
     local p = evo.idpools.idpool()
 
     for _ = 1, 0xFFFFF - 1 do
-        _ = evo.idpools.acquire_id(p)
+        _ = evo.idpools.acquire(p)
     end
 
-    assert(evo.idpools.acquire_id(p) == 0x1FFFFF)
+    assert(evo.idpools.acquire(p) == 0x1FFFFF)
 
     if not os.getenv("LOCAL_LUA_DEBUGGER_VSCODE") then
-        assert(not pcall(evo.idpools.acquire_id, p))
+        assert(not pcall(evo.idpools.acquire, p))
     end
 end
 
@@ -73,14 +73,26 @@ do
     local p = evo.idpools.idpool()
 
     for _ = 1, 0x7FF - 1 do
-        evo.idpools.release_id(p, evo.idpools.acquire_id(p))
+        evo.idpools.release(p, evo.idpools.acquire(p))
     end
 
-    local i1_7FF = evo.idpools.acquire_id(p)
+    local i1_7FF = evo.idpools.acquire(p)
     assert(i1_7FF == 0x7FF00001)
-    evo.idpools.release_id(p, i1_7FF)
+    evo.idpools.release(p, i1_7FF)
 
-    local i1_1 = evo.idpools.acquire_id(p)
+    local i1_1 = evo.idpools.acquire(p)
     assert(i1_1 == 0x100001)
-    evo.idpools.release_id(p, i1_1)
+    evo.idpools.release(p, i1_1)
+end
+
+for _ = 1, 100 do
+    local o_index = math.random(0xFFFFF)
+    local o_version = math.random(0x7FF)
+
+    local id = evo.idpools.pack(o_index, o_version)
+
+    local r_index, r_version = evo.idpools.unpack(id)
+
+    assert(o_index == r_index)
+    assert(o_version == r_version)
 end

evolved/idpools.lua

@@ -17,10 +17,19 @@ function idpools.idpool()
     return setmetatable(idpool, evolved_idpool_mt)
 end
 
+---@param index integer
+---@param version integer
+---@return integer
+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
 ---@return integer index
 ---@return integer version
-function idpools.unpack_id(id)
+function idpools.unpack(id)
     local index = id % 0x100000
     local version = (id - index) / 0x100000
     return index, version
@@ -29,31 +38,33 @@ end
 ---@param idpool evolved.idpool
 ---@return integer
 ---@nodiscard
-function idpools.acquire_id(idpool)
+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 acquired_id = index + version
+        idpool.__acquired_ids[index] = acquired_id
+        return acquired_id
+    else
+        if #idpool.__acquired_ids == 0xFFFFF then
+            error('id index overflow', 2)
+        end
+
+        local index = #idpool.__acquired_ids + 1
+        local version = 0x100000
+
         local acquired_id = index + version
         idpool.__acquired_ids[index] = acquired_id
         return acquired_id
     end
-
-    if #idpool.__acquired_ids == 0xFFFFF then
-        error('id index overflow', 2)
-    end
-
-    local index = #idpool.__acquired_ids + 1
-    local version = 0x100000
-    local acquired_id = index + version
-    idpool.__acquired_ids[index] = acquired_id
-    return acquired_id
 end
 
 ---@param idpool evolved.idpool
 ---@param id integer
-function idpools.release_id(idpool, id)
+function idpools.release(idpool, id)
     local index = id % 0x100000
     local version = id - index
 
@@ -73,7 +84,7 @@ end
 ---@param id integer
 ---@return boolean
 ---@nodiscard
-function idpools.is_id_alive(idpool, id)
+function idpools.is_alive(idpool, id)
     local index = id % 0x100000
     return idpool.__acquired_ids[index] == id
 end

evolved/registry.lua

@@ -250,7 +250,7 @@ end
 ---@return evolved.entity
 ---@nodiscard
 function registry.entity()
-    local guid = idpools.acquire_id(__guids)
+    local guid = idpools.acquire(__guids)
 
     ---@type evolved.entity
     local entity = {
@@ -266,7 +266,7 @@ end
 ---@return boolean
 ---@nodiscard
 function registry.is_alive(entity)
-    return idpools.is_id_alive(__guids, entity.__guid)
+    return idpools.is_alive(__guids, entity.__guid)
 end
 
 ---@param entity evolved.entity
@@ -279,7 +279,7 @@ function registry.destroy(entity)
         __detach_entity(entity)
     end
 
-    idpools.release_id(__guids, entity.__guid)
+    idpools.release(__guids, entity.__guid)
 end
 
 ---@param entity evolved.entity
@@ -520,7 +520,7 @@ end
 ---
 
 function evolved_entity_mt:__tostring()
-    local index, version = idpools.unpack_id(self.__guid)
+    local index, version = idpools.unpack(self.__guid)
 
     return string.format('[%d;%d]', index, version)
 end