[Guide] Memory management

[paladin-t]

There are two major memory management methods in computer programming, manual releasing and auto releasing. While Bitty Engine uses Lua, it benefits from Garbage Collecting which is a type of auto releasing method, so a user can focus on program logic other than memory details. This article guides you understanding and practicing with Bitty Engine's memory management.

Lua's Garbage Collection

Lua implements two GC modes, incremental and generational.

"In incremental mode, each GC cycle performs a mark-and-sweep collection in small steps interleaved with the program's execution."

"In generational mode, the collector does frequent minor collections, which traverses only objects recently created. If after a minor collection the use of memory is still above a limit, the collector does a stop-the-world major collection, which traverses all objects."

Bitty Engine uses the generational mode (a.k.a. collectgarbage('generational')) by default.

Bitty Engine's Resources.collect()

Assets are loaded as resources before rendering in Bitty Engine, then cached for better performance. A variable value that holds a loaded resource are managed by GC, however the resource itself won't be auto released until you do it manually.

Consider Resources.unload(...) to unload each unused resource properly, or in a simpler way Resources.collect() to determine automatically and unload all unused resources. Call this function when a new level is loaded and the old one is obsolete, etc.

Memory Management Patterns

Consider an appropriate pattern in practice for better overall balance among "less code modification", "memory efficiency" and "CPU efficiency", although GC manages memory automatically.

1. Default

You don't need to do any extra step to use the default GC pattern for small programs, prototypes, and other programs that won't allocate very often. Thus with this pattern, it doesn't add extra CPU load. But you might see continuous footprint increasing along with continuous running.

2. Periodical Collecting

The second pattern is to use a frame/time counter to accumulate how long the program has ran, then collect garbage after every constant interval, i.e.

local GC_INTERVAL_FRAMES <const> = 60 * 5 -- Around 5 seconds.
local n = 0

function update(delta)
  n = n + 1
  if n >= GC_INTERVAL_FRAMES then
    n = 0
    collectgarbage()
    Resources.unload()
  end
end

This pattern requires a few more lines of code. The footprint will be maintained under a reasonable level, even after long time run. The time counting and manual collecting code won't add remarkable CPU load. But the manual releasing might lead to unexpected short pause if there were more garbage than usual.

3. Fine Collecting

The final pattern offers fine management, it doesn't come with standard routine. You can organize it in your own way according to specific project, i.e. call collecting when a new level is loaded, a new GUI pops up, a number of enemies are defeated, etc.

function onSomethingHappened()
  collectgarbage()
  Resources.unload()
end

You can also mix the Periodical and Fine Collecting patterns together.

Finally, try adjusting the GC options to optimize your program:

• collectgarbage ([opt [, arg1 [, arg2]]]): This function is a generic interface to the garbage collector. It performs different functions according to its first argument, opt:
  • "collect": Performs a full garbage-collection cycle.
  • "stop": Stops the garbage collector.
  • "restart": Restarts the garbage collector.
  • "count": Returns the total memory in use by Lua in Kbytes. The value has a fractional part, so that it multiplied by 1024 gives the exact number of bytes in use by Lua.
  • "step" (n): Performs a step of garbage collection.
  • "isrunning": Returns a boolean that tells whether the collector is running (i.e., not stopped).
  • "incremental": Changes the collector to incremental mode. Returns the previous mode ("generational" or "incremental").
  • "generational": Changes the collector to generational mode. Returns the previous mode ("generational" or "incremental").
  • "param" (param, val): Changes and/or returns the value of a parameter of the collector. If val is -1, the call only returns the current value. The argument param must have one of the following values:
    • "minormul": The minor multiplier.
    • "majorminor": The major-minor multiplier.
    • "minormajor": The minor-major multiplier.
    • "pause": The garbage-collector pause.
    • "stepmul": The step multiplier.
    • "stepsize": The step size.