keiki

--[[
***************************************************************
    * > keiki object pooler
    *
    * > can pool up to 65536 objects at once.
    * > designed to be used with callbacks, so you can
        *   customize pools to your heart's content.
    *
    * > by suwacrab 2020:28:06
***************************************************************
--]]

local keiki = {}
keiki.__index = keiki


--|==== function reference ===|
--[[
    * > function list:
    * keiki.new(len,def): creates new list w/ length `len` and optional callback `def`
    * keiki:add(mode,f) : adds new object w/ mode `mode` and optional callback `f`
    * keiki:del(id,f)   : deletes object [id] and uses optional callback `f`
    * keiki:iter(f)     : iterates through pool with callback `f`
    *
    * > structure info:
    * every pool has 4 attributes:
        ・objs: the (0-indexed!) array of objects
        ・len: the length of objects
        ・last: a pointer to the last object in the
            pool. this is used for adding and removing
            objects from the pool's free list
        ・alive: the number of alive objects
    * every object has 4 attributes, but you're free to add more to them:
        ・mode: the object's "type". you can use this
            for using different types of objects inside one pool.
        ・dead: whether or not the object's alive.
        ・id: the object's index in the array.
        ・next: a pointer to the next object. used for the pool's free
            list.
]]


--|==== functions =============|
-- * > creates a new object pool
-- * ・len: length of army, must be under 0x10000.
-- * ・def: callback on every object. 1st is the list,2nd is index.
keiki.new = function(len,def)
    local may = { objs = {},len = len,last = 0,alive = 0 }
    for i = 0,len-1 do
        may.objs[i] = { mode=0,dead=true,id=i,next=i+1 }
        if def then def(may,i,may.objs[i]) end
    end
    may.objs[len-1].next = 0xFFFF

    return setmetatable(may,keiki)
end

--> adds a new object to pool.
-- > may: the list to add to
-- > mode: the type of object
-- > f: the callback on the new object. works the same as keiki.new's callback.
keiki.add = function(may,mode,f)
    -- if there's no space, return nil.
    if may.alive == may.len then return end
    -- find the nearest object, reset it's attributes
    local hani = may.objs[may.last]
    hani.dead = false
    hani.mode = mode or 0;
    if f then f(may,hani.id,hani) end
    -- make sure this object will be the next free object once it's dead
    may.last = hani.next
    -- increment the alive count, then return the new object.
    may.alive = may.alive+1
    return hani;
end

--> deletes object [id] from the pool.
-- > may: the list to remove from
-- > id: the id of the object to remove.
-- > f: callback on the deleted object. works the same as keiki.new's callback.
keiki.del = function(may,id,f)
    -- if the deleted object doesn't exist, return nil.
    local hani = may.objs[id]
    if(hani==nil) then return end
    -- reset variables.
    hani.dead = true
    if f then f(may,hani.id,hani) end
    -- hani's next object should be the last free object
    -- the new free object should be hani
    hani.next = may.last
    may.last = id
    -- decrement alive counter
    may.alive = may.alive-1
    return hani
end

--> iterates through pool with the callback f.
-- > may: the pool to iterate through
-- > f: the callback to use.
-- >> 1st argument is the list, 2nd is the id, 3rd is the current object.
keiki.iter = function(may,f)
    for i = 0,may.len-1 do
        f(may,i,may.objs[i])
    end
end

return keiki