NAME

src/gc/api.c - general Parrot API for GC functions

DESCRIPTION

This file implements dead object destruction. This is documented in PDD 9 with supplementary notes in docs/dev/dod.pod and docs/memory_internals.pod.

It's possible to turn on/off the checking of the system stack and processor registers. The actual checking is set up in src/cpu_dep.c and is performed in the function trace_memory_block here.

There's also a verbose mode for garbage collection.

FUNCTIONS

PMC *new_pmc_header

Gets a new PMC header from the PMC pool's free list. Guaranteed to return a valid PMC object or else Parrot will panic. Sets the necessary flags for the objects and initializes the PMC data pointer to NULL.

static PMC_EXT *new_pmc_ext

Gets a new free PMC_EXT structure from the PMC_EXT pool. A pointer to the new PMC_EXT is returned. Does not check to ensure the PMC_EXT is non-null before it is returned (yet).

void add_pmc_ext

Obtains a new PMC_EXT structure, and attaches it to the given PMC. Sets the necessary flags associated with the PMC_EXT structure. Ensures that the PMC_EXT structure is marked as "alive" by the GC.

void add_pmc_sync

Adds a Sync* structure to the given PMC. Initializes the PMC's owner field and the synchronization mutext. Does not check to ensure the Sync * is non-null.

STRING *new_string_header

Returns a new STRING header from the string pool or the constant string pool. Sets default flags on the string object: PObj_is_string_FLAG, PObj_is_COWable_FLAG, and PObj_live_FLAG (for GC). Initializes the data field of the string buffer to NULL.

Buffer *new_buffer_header

Creates and returns a new Buffer from the buffer header pool. Calls get_free_buffer to do all the work.

void *new_bufferlike_header

Returns a new buffer-like header from the appropriate sized pool.

void Parrot_gc_free_pmc

Frees a PMC that is no longer being used. Calls a custom destroy VTABLE method if one is available. If the PMC uses a PMC_EXT structure, that is freed as well.

void Parrot_gc_free_pmc_ext

Frees the PMC_EXT structure attached to a PMC, if it exists.

void Parrot_gc_free_sysmem

If the PMC uses memory allocated directly from the system, this function frees that memory.

void Parrot_gc_free_buffer_malloc

Frees the given buffer, returning the storage space to the operating system and removing it from Parrot's memory management system. If the buffer is COW, The buffer is not freed if the reference count is greater then 1.

void Parrot_gc_free_buffer

Frees a buffer, returning it to the memory pool for Parrot to possibly reuse later.

static size_t find_common_mask

Finds a mask covering the longest common bit-prefix of val1 and val2.

void trace_mem_block

Traces the memory block between lo_var_ptr and hi_var_ptr. Attempt to find pointers to PObjs or buffers, and mark them as "alive" if found. See src/cpu_dep.c for more information about tracing memory areas.

void Parrot_gc_profile_start

Records the start time of a DOD run when profiling is enabled.

void Parrot_gc_profile_end

Records the end time of the DOD part what run when profiling is enabled. Also record start time of next part.

void Parrot_gc_ms_run_init

Prepares the collector for a mark & sweep DOD run. This is the initializer function for the MS garbage collector.

void Parrot_do_dod_run

Calls the configured garbage collector to find and reclaim unused headers.

SEE ALSO

include/parrot/gc_api.h, src/cpu_dep.c, docs/dev/dod.dev and docs/pdds/pdd09_gc.pod.

HISTORY

Initial version by Mike Lambert on 2002.05.27.