# `nupp.mem.arena` A paged allocator of struct rows whose pages never move. Rows are handed out in order from fixed-size pages of one struct type. A page is allocated once and stays where it is, so a row reference is good for as long as the arena is; growth adds a page beside the others rather than moving anything. A reset rewinds to the first row of the first page and keeps every page, which is what makes the next epoch allocation-free. ```nupp local arena = nupp.mem.arena local struct Impact x: float y: float end local impacts = arena.new(Impact, 256) local impact = impacts:acquire() -- zero-filled impact.x = 1.5 impacts:release(impact) impacts:reset() -- rewinds; the page stays ``` Every acquired row reads as zero, whether it is fresh or one a reset made available again. A release ends a lease and nothing more: the cursor does not rewind until `reset`, and `reset` refuses while any lease is live, so a row that is out is never handed out twice. Storage comes from the `cstorage` capability, so the module is available on native LuaJIT and on the Wasm and browser backends, and refused by `portable`. Table-backed record instances are `nupp.mem.pool`. ## Constructors ### `arena.new` _constructor_ ```nupp function arena.new(witness: Type, pageSize: integer?): arena.Arena ``` Creates an arena of `witness` rows with one page of `pageSize` rows already allocated. ```nupp local struct Cell value: int32 end local cells = arena.new(Cell, 16) assert(cells:pages() == 1 and cells:used() == 0) ``` #### Type parameters | Name | Description | | --- | --- | | `S` | | #### Arguments | Name | Type | Description | | --- | --- | --- | | `witness` | `Type\` | the struct declaration every row is laid out as | | `pageSize` | `integer?` | rows per page, 256 when omitted | #### Returns | Type | Description | | --- | --- | | `arena.Arena\` | the arena, holding its first page | #### Raises - when pageSize is not a positive integer ## Types ### `Arena` _record_ ```nupp record arena.Arena readonly pageSize: integer acquire: function(exclusive self: Arena): S release: function(exclusive self: Arena, row: S): nil reset: function(exclusive self: Arena): nil pages: function(self: Arena): integer used: function(self: Arena): integer live: function(self: Arena): integer end ``` A paged allocator of rows of one struct type. #### Type parameters | Name | Description | | --- | --- | | `S` | | #### Methods ##### `acquire` ```nupp acquire: function(exclusive self: Arena): S ``` Hands out the next row, zero-filled. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `Arena\` | | ###### Returns | Type | Description | | --- | --- | | `S` | | ##### `release` ```nupp release: function(exclusive self: Arena, row: S): nil ``` Ends a lease without rewinding the cursor. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `Arena\` | | | `row` | `S` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ###### Raises - when no lease is live ##### `reset` ```nupp reset: function(exclusive self: Arena): nil ``` Rewinds every used page's cursor and keeps the pages. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `Arena\` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ###### Raises - when any lease is live ##### `pages` ```nupp pages: function(self: Arena): integer ``` How many pages the arena holds. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Arena\` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `used` ```nupp used: function(self: Arena): integer ``` How many rows were handed out since the last reset. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Arena\` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `live` ```nupp live: function(self: Arena): integer ``` How many rows are acquired and not yet released. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Arena\` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | #### Fields ##### `pageSize` ```nupp pageSize: integer ``` How many rows each page holds.