Memory Allocation and Garbage Collection

MAXScript allocates its own working memory in addition to any memory 3ds Max allocates as it works.

The default working memory size setting for MAXScript is 15 MB, and the memory is virtual and pageable like all 3ds Max memory.

The default allocation accommodates most tasks, but you can increase it by incrementing the MAXScript system global variable heapSize :

heapSize += 2000000 -- another 2 MB, for a total of 9.5 MB

You can add this statement to your startup script if you always need extra memory allocated for MAXScript tasks or you can set the default size in the MAXScript tab in the 3ds Max Customize>Preferences dialog.

Increasing the MAXScript heap reduces memory address space for other 3ds Max tasks.

Adjust the default memory setting only after you receive "Out of memory" error messages from MAXScript, or when garbage collection pauses occur frequently.

You can increase the MAXScript heap as many times as you need during a 3ds Max session, but you cannot reduce it.

Restart 3ds Max to reset the MAXScript memory heap to the default setting.

MAXScript uses a memory management scheme called automatic garbage collection.

This means you don’t have to explicitly reclaim any memory that a value takes up when you no longer need it.

When you assign a new value to a variable or when a local variable’s block exits, the reference that the variable contained is dropped.

When your program has dropped all references to a value's memory, that memory becomes eligible for reclamation.

Some values, such as arrays, have internal references to other values.

In an array, each element contains a reference to another value.

When you assign a new value to an array element, the element's old reference is dropped.

If you remove all references to the array itself, all the references in the elements of that array are implicitly dropped.

The same applies to component values, such as in user structures and most 3ds Max objects.

MAXScript reclaims memory in a garbage collection pass through memory when MAXScript runs out of memory.

This simple approach can result in a short pause because the entire MAXScript memory is scanned for garbage.

The advantage of garbage collection is you can create as many values as you need, and MAXScript cleans up the ones you no longer use.

In 3ds Max 9, the HeapSize and the HeapFree system variables were changed from Integer to Integer64 to accommodate the increased memory address space of 64 bit systems.

In 3ds Max 9 and higher, the initial heap size is limited to 512MB.

If the initial heap size is still too high and the specified memory block cannot be allocated, the initial heap size is recursively decreased by 10% until the memory block can be allocated.

If a 1MB memory block cannot be allocated, an assert is triggered and the 3ds Max session is terminated (if the system cannot allocate 1MB at startup, something is very wrong).

Otherwise, a message is displayed in the status panel stating that the requested heap size was automatically decreased, and gives the actual heap size allocated.

A test was added to ensure that the initial heap size is at least the absolute minimum required by MAXScript - 12 bytes.

Code was added so that as new values are allocated, the heap size is automatically increased if necessary (requested memory size not available in the heap after performing a full garbage collection) .

The first attempted increase is the maximum of 50* the requested size or 512KB.

If this allocation fails, a series of allocation attempts is made with decreasing allocation sizes, with the last one being the maximum of the requested size or 256KB.

If this final allocation attempt fails, a runtime error is thrown.

Otherwise, a message is displayed in the status panel stating that the requested heap size was automatically increased, and gives the new heap size.

heapCheck() 	 

The heapCheck() method is mostly for internal debugging.

It can be called by scripts to perform a minimal consistency check of the Heap.

Available in 3ds Max 9 and higher.

Possible return values are:

OK - Heap appears to be consistent (_HEAPOK)

-1 - Heap has not been initialized (_HEAPEMPTY)

-3 -Initial header information is bad or cannot be found.(_HEAPBADBEGIN)

-4 -Bad node has been found or heap is damaged.(_HEAPBADNODE)

-6 - Pointer into Heap is not valid (_HEAPBADPTR)

See also the CRT Debug Functions topic for related methods.