collector from time to time to collect all dead objects
(that is, these objects that are no longer accessible from Lua). All objects
in Lua are subject to automatic management: tables, userdata, functions,
threads, and strings.

Lua implements an incremental mark-and-sweep collector. It uses two numbers to
control its garbage-collection cycles: the garbage-collector pause and the
garbage-collector step multiplier.

The garbage-collector pause controls how long the collector waits before
starting a new cycle. Larger values make the collector less aggressive. Values
smaller than 1 mean the collector will not wait to start a new cycle. A value
of 2 means that the collector waits for the total memory in use to double
before starting a new cycle.

The step multiplier controls the relative speed of the collector relative to
memory allocation. Larger values make the collector more aggressive but also
increase the size of each incremental step. Values smaller than 1 make the
collector too slow and may result in the collector never finishing a cycle.
The default, 2, means that the collector runs at "twice" the speed of memory
allocation.

You can change these numbers by calling `lua_gc` (see |lua_gc()|) in C or
`collectgarbage` (see |collectgarbage()|) in Lua. Both get percentage points
as arguments (so an argument of 100 means a real value of 1). With these
functions you can also control the collector directly (e.g., stop and restart
it).

------------------------------------------------------------------------------
2.10.1  Garbage-Collection Metamethods                       *lua-gc-meta*

Using the C API, you can set garbage-collector metamethods for userdata (see
|lua-metatable|). These metamethods are also called finalizers.
Finalizers allow you to coordinate Lua's garbage collection with external
resource management (such as closing files, network or database connections,
or freeing your own memory).

                                                                          *__gc*
Garbage userdata with a field `__gc` in their metatables are not collected
immediately by the garbage collector. Instead, Lua puts them in a list. After
the collection, Lua does the equivalent of the following function for each
userdata in that list:
>lua
       function gc_event (udata)
         local h = metatable(udata).__gc
         if h then
           h(udata)
         end
       end
<
At the end of each garbage-collection cycle, the finalizers for userdata are
called in reverse order of their creation, among these collected in that
cycle. That is, the first finalizer to be called is the one associated with
the userdata created last in the program.

------------------------------------------------------------------------------
2.10.2 - Weak Tables                            *lua-weaktable*

A weak table is a table whose elements are weak references. A weak reference
is ignored by the garbage collector. In other words, if the only references to
an object are weak references, then the garbage collector will collect this
object.

                                                                        *__mode*
A weak table can have weak keys, weak values, or both. A table with weak keys
allows the collection of its keys, but prevents the collection of its values.
A table with both weak keys and weak values allows the collection of both keys
and values. In any case, if either the key or the value is collected, the
whole pair is removed from the table. The weakness of a table is controlled by
the value of the `__mode` field of its metatable. If the `__mode` field is a
string containing the character `k`, the keys in the table are weak.
If `__mode` contains `v`, the values in the table are weak.

After you use a table as a metatable, you should not change the value of its
field `__mode`. Otherwise, the weak behavior of the tables controlled by this
metatable is undefined.

==============================================================================
2.11