Memory Allocation

MzScheme uses both malloc and allocation functions provided the conservative garbage collector. Embedding/extension C/C++ code may use either allocation method, keeping in mind that pointers to garbage-collectable blocks in malloced memory are invisible (i.e., such pointers will not prevent the block from being garbage-collected).

The garbage collector normally only recognizes pointers to the beginning of allocated objects. Thus, a pointer into the middle of a GC-allocated string will normally not keep the string from being collected. The exception to this rule is that pointers saved on the stack or in registers may point to the middle of a collectable object. Thus, it is safe to loop over an array by incrementing a local pointer variable.

The collector allocation functions are:

• scheme_malloc -- Allocates collectable memory that may contain pointers to collectable objects.
• scheme_malloc_atomic -- Allocates collectable memory that does not contain pointers to collectable objects. If the memory does contain pointers, they are invisible to the collector and will not prevent an object from being collected.

  Atomic memory is used for strings or other blocks of memory which do not contain pointers. Atomic memory can also be used to store intentionally-hidden pointers.

• scheme_malloc_stubborn -- Allocates collectable memory that may contain pointers to collectable objects, but also has special properties to support generational collection. Once the content of the allocated memory is set, call scheme_end_stubborn_change; this function call serves as a promise that the memory's contents will never be changed again (until after it is garbage-collected).
• scheme_malloc_uncollectable -- Allocates uncollectable memory that may contain pointers to collectable objects. There is no way to free the memory.

If a MzScheme extension stores Scheme pointers in a global variable, then that variable must be registered with scheme_register_extension_global; this makes the pointer visible to the garbage collector. No registration is needed for the global variables of an embedding program.

Collectable memory can be temporarily locked from collection by using the reference-counting function scheme_dont_gc_ptr.

• Library Functions