Arena-style memory management in Ruby.

Class Method Summary

.allocate

def allocate(objects: , storage: 0) # => Object 

Allocates a new GC::Arena, reserving a pool of memory for objects and their backing data.

@return GC::Arena

Parameters

Instance Method Summary

#eval

def eval { ... } # => Object 

Substitutes this Arena in place of the current object pool and allocator, forcing object creation within the given block to occur within this Arena.

• Nested calls to GC:::Arena#eval should function as expected.
• Allocations performed by C extensions will also utilize this Arena if they perform allocations using the mruby provided APIs.

Returns

• The block's result.

#reset

def reset # => nil 

Resets the Arena's allocator.

This enables scratch and periodic Arenas to quickly and quietly discard all data and prepare for further use. Manually resetting is faster than allocating a new Arena, and substantially faster than delegating to the GC.

Examples

$scratch = Arena.new(objects: 2048)
def tick(...)
  $scratch.reset
  $scratch.eval do
    simulate_game
    render_game
  end
end

Returns

• nil

#stats

def stats # => Hash 

Provides details about the utilization of this Arena. These details can be used to determine appropriate values for preallocation, by inspecting these values either after the Arena has been fully populated or periodically just before resetting the Arena (to determine a "high water mark" for object/memory consumption).

Returns

• Hash — Detailed statistics about this Arena.
  • pages
    • This indicates the number of memory pages that have been allocated since the Arena was created. Numbers greater than 1 indicate that usage has exceeded the initialization capacity.
  • total_objects
    • This represents the total number of object slots currently available.
  • live_objects
    • This represents the number of object slots which have been filled since the Arena was created.
  • free_objects
    • This represents the number of unpopulated object slots.
  • total_storage
    • This represents the total number of bytes allocated for additional object data storage.
  • used_storage
    • This represents the number of bytes of additional object storage currently being used.
  • free_storage
    • This represents the number of bytes allocated but as-yet unused.
    • Note that this number may be higher than expected, as data near the end of a page may be left indefinitely "free" if the next allocation is larger than the remaining available space.