Collectgarbage – It does what it says it does

Definition

collectgarbage ([opt [, arg]])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. This is the default option.
• “stop”: stops the garbage collector.
• “restart”: restarts the garbage collector.
• “count”: returns the total memory in use by Lua (in Kbytes).
• “step”: performs a garbage-collection step. The step “size” is controlled by arg (larger values mean more steps) in a non-specified way. If you want to control the step size you must experimentally tune the value of arg. Returns true if the step finished a collection cycle.
• “setpause”: sets arg as the new value for the pause of the collector. Returns the previous value for pause.
• “setstepmul”: sets arg as the new value for the step multiplier of the collector. Returns the previous value for step.

For now, let’s just focus on the collect and count options.

Let’s look at a few examples

We’ll just try a few things out and see how they’ll run. Remember to click on the green button to see what acctually happens with the code.

Counting memory usage

To find the number of kilobytes currently in use by Lua, you can simply make a call with count.

What you see in the console is the memory usage before and after the assignment. You should see around \sim 21 – 22 bytes of memory used up by the assignment.

Forcing a full run of garbage collection

If we don’t specify an option, then Lua will perform a full collection

Found in the wild

To top it off, let’s look at some real world uses of collectgarbage.

Keeping track of memory usage

This is usually used during “profiling”, or checking the performance of your code. For the most part, keeping an eye on the memory usage may ensure that your code doesn’t go through some crazy mood cycle and decide to blow up on you at the most unexpected time. For the most part however, since Lua still automates collection and keeps track of every by itself, this is unnecessary.

When you create new objects instead of reusing older ones

Since the notion of memory seems like such a faraway concept in Lua, it is easy to often forget that creating new objects take up memory, and certain patterns of coding could end up using up memory and then immediately discarding it faster than Lua can reclaim the wasted space.

In one extremely contrived example, there’s a good analogy of that new kid at school who wants to pretend to be cool, so he drew a mustache on his face on his first day; in the marginally more mature world of programming, that new kid is the guy who just read the wikipedia article on “lambda-calculus” (haven’t heard of it yet? don’t worry, you’re not going to need it unless you want to be a theoretical computer scientist) and decides to rub his knowledge in on /r/learnprogramming.

Now, this guy wants to implement the number one million through one million function calls to stay true to his “hip”ness, so he decides to write the following function to do just that. (Don’t worry about a function calling itself, it usually does what you think it will do)

(Note: be very cautious when running that code, it does take a fair bit of memory and time so it may freeze your browser up)

It might not make sense that just calling functions and immediately discarding them could incur up so much memory usage, but just for the sake of illustration, just pretend that each function is equivalent to a table and that each function call is equivalent to looking up some element within that table that also turns out to be a table. In this case, we only care about the millionth inner nested table and none of the other ones; but in order to get to that inner nested table, we still need to keep the other tables in memory. Now to make matters worse, in the case of functions, we’re creating those tables on the go.

Anyways, do another collection and see how much memory was freed.