Manual Garbage Collection

The function gc() invokes the garbage collector. Normally, the collector runs automatically when available memory runs low, so you don't normally need to call it explicitly. However, in some situations, it is useful to be able to force a collect to ensure a pause due to garbage collection will be delayed as long as possible.

You can also invoke the collector to cause any unreferenced open files to be closed. In some situations, a file can be left open if a runtime error occurs while it is still open. If the file object was being held in a local variable at this point, it may not be possible to get at it from the Listener to force a close. Any subsequent attempts to open it may result in an "already open" error from the operating system. Running the collector will cause the file object to be reclaimed and this forces any open file associated with it to be closed.

gc [light:false] [delayed:false]


This function returns the number of bytes free in the MAXScript heap after collection. Note that the collector may take many seconds to run if the heap is full of many small reclaimable objects.

Garbage Collection light option

When the optional light keyword argument is passed as true, the undo buffer will not be flushed. If you are performing a lot of scene operations then it is recommended to call gc() without any argument or pass light:false, in which case the undo buffer will be flushed prior to the garbage collection.

When light:true is specified, any value that derives from MAXWrapper will not be collected. This covers all value types that could potentially be in the undo buffer. The result is that, for this case, less memory is released and gc runs a bit slower, but you can't corrupt the undo stack. If light:true is not specified, behavior and speed is same as before.

What does get collected with light:true includes rollouts, floaters, UI items, bitmaps, strings, arrays, and bitArrays. Those are all items that do not exist in the scene.

Automatic Garbage Collection behavior and delayed: option

When MAXScript runs out of heap memory, it runs garbage collection to free unused memory. Since a value collected may be the last reference to a MAX object, we need to flush the undo system since it may contain a pointer to that object or one of its dependents.

In 3ds Max 5, the 'light' keyword argument has been introduced for manual garbage collection where, if true, MAXWrapper-derived values are not garbage collected, thus no MAX objects are deleted, and no flush of the undo system is required.

The change to MAXScript in 3ds Max 6 extends this to automatic garbage collection. When an automatic garbage collection is performed, and the undo system is not empty, an initial garbage collection is performed where MAXWrappers are not garbage collected, and a flag is set so that on the next undo system flush, a full garbage collection is performed. If this initial garbage collection does not free up sufficient memory to satisfy the memory request, or if the undo system is empty, a full garbage collection is performed where MAXWrappers are deleted and the undo system is flushed.

With the recent improvements in MAXWrapper interning, undo system flushes due to MAXScript garbage collection should be a fairly rare event.

To maintain current behavior, a manual garbage collection using 'gc()' still flushes the undo system. gc light:true will still not flush the undo system.

The delayed:<boolean> option will cause a full garbage collection at the next undo system flush. So the user could say the following to match the behavior of an automatic garbage collection:

gc light:true delayed:true



See also

Memory Allocation and Garbage Collection