nupp.mem.pool

A pool of record instances of one declared type.

An instance leaves the pool stamped with the declaration and carrying no fields, and comes back cleared, so a hot path that would otherwise build a table per event reuses the ones it already built.

local pool = nupp.mem.pool

local record Damage
    amount: integer
    source: string
end

local damage = pool.new(Damage, 64)
local hit = damage:acquire()
hit.amount = 12
hit.source = "trap"
damage:release(hit) -- cleared, and kept for the next acquire

capacity is how many released instances the pool keeps; it is not a limit on how many are out at once. An acquire past the free list allocates, and a release onto a full free list lets the collector have the instance. Within capacity, once the free list is warm, neither operation allocates.

Nothing here reaches C storage: the pool is ordinary tables, so it is available on every backend. Struct rows are nupp.mem.arena.

function pool.new<T is table>(witness: Type<T>, capacity: integer?): pool.Pool<T>

local record Tick
    frame: integer
end

local ticks = pool.new(Tick, 8)
assert(ticks:free() == 8)

record pool.Pool<T is table>
    readonly capacity: integer
    acquire: function(exclusive self: Pool<T>): T
    release: function(exclusive self: Pool<T>, value: T): nil
    reserve: function(exclusive self: Pool<T>, count: integer): nil
    live: function(self: Pool<T>): integer
    free: function(self: Pool<T>): integer
    reset: function(exclusive self: Pool<T>): nil
end

acquire: function(exclusive self: Pool<T>): T

release: function(exclusive self: Pool<T>, value: T): nil

reserve: function(exclusive self: Pool<T>, count: integer): nil

live: function(self: Pool<T>): integer

free: function(self: Pool<T>): integer

reset: function(exclusive self: Pool<T>): nil

capacity: integer