NAME

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

DESCRIPTION

This file implements the external-facing API for Parrot's garbage collector. The collector itself is composed of various interchangable cores that each may operate very differently internally. The functions in this file can be used throughtout Parrot without having to be concerned about the internal operations of the GC. This is documented in PDD 9 with supplementary notes in docs/memory_internals.pod.

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.

void Parrot_gc_profile_start

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

void Parrot_gc_profile_end

Records the end time of the GC mark run 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 GC run. This is the initializer function for the MS garbage collector.

void Parrot_do_gc_run

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

SEE ALSO

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

HISTORY

Initial version by Mike Lambert on 2002.05.27.