[svn:parrot] r40015 - trunk/src/gc

whiteknight at svn.parrot.org whiteknight at svn.parrot.org
Sun Jul 12 13:29:56 UTC 2009


Author: whiteknight
Date: Sun Jul 12 13:29:53 2009
New Revision: 40015
URL: https://trac.parrot.org/parrot/changeset/40015

Log:
[gc] add some more helpful documentation to gc_inf to explain what each function is used for

Modified:
   trunk/src/gc/gc_inf.c

Modified: trunk/src/gc/gc_inf.c
==============================================================================
--- trunk/src/gc/gc_inf.c	Sun Jul 12 12:48:53 2009	(r40014)
+++ trunk/src/gc/gc_inf.c	Sun Jul 12 13:29:53 2009	(r40015)
@@ -15,7 +15,9 @@
 Because this core never frees memory, some functionality is missing and some
 tests will fail: Tests for timely destruction, tests involving IO that is
 not manually flushed (the GC never calls the destroy VTABLE, so things never
-get flushed/closed automatically), etc.
+get flushed/closed automatically), etc. This is by design and should not be
+considered a "bug" or an "error". It is just a fact of life for such a
+minimalist core.
 
 To enable this core, change the settings in include/parrot/settings.h. Set
 
@@ -46,6 +48,14 @@
 This function would perform a GC run, if we needed to. Luckily we have
 infinite memory!
 
+This function is called from the GC API function C<Parrot_gc_mark_and_sweep>.
+
+Flags can be a combination of these values:
+
+  GC_finish_FLAG
+  GC_lazy_FLAG
+  GC_trace_stack_FLAG
+
 =cut
 
 */
@@ -60,7 +70,13 @@
 =item C<void gc_inf_add_free_object(SHIM_INTERP, Small_Object_Pool *pool,
     void *to_add)>
 
-Manually frees a chunk of memory.
+Manually frees a chunk of memory. Normally this would return the memory
+to the free list of the pool, but in this case we just return it to the
+OS.
+
+This function is called from places like C<Parrot_gc_free_pmc_header> and
+related manual freeing functions. Some cores will also use it internally to
+add items to the freelist from a freshly allocated arena.
 
 =cut
 
@@ -78,7 +94,19 @@
 
 =item C<void *gc_inf_get_free_object(PARROT_INTERP, Small_Object_Pool *pool)>
 
-Gets a new buffer from memory of the required size
+Gets a new object from the pool. Each pool specifies an object size in
+C<pool->object_size> so we can use that number to make the allocation. For
+GCs that manage their own memory through the use of arenas or similar
+structures, we can use this basic algorithm here:
+
+ 1) Check if we have any items on the free list and allocate one from there
+    if so.
+ 2) Do a GC run to try and free up new items, and allocate a newly freed
+    item if one becomes available
+ 3) Allocate a new arena from the OS and allocate a new item from there.
+
+This function is called from GC API functions like
+C<Parrot_Gc_get_new_pmc_header>
 
 =cut
 
@@ -94,7 +122,12 @@
 
 =item C<void gc_inf_alloc_objects(PARROT_INTERP, Small_Object_Pool *pool)>
 
-Allocates a new arena of objects from the system. Actually, it doesn't here.
+Allocates a new arena of objects from the system. This function is only
+really used internally by the core, the API functions don't need to call
+it directly. However, this function is necessary because we may have
+different behaviors for certain pools, so we can't allocate for all of them
+in the same way. We will need to have a new "alloc_objects" function
+for each special case pool.
 
 =cut
 
@@ -111,7 +144,11 @@
 
 Would normally try to find new traceable objects by first running a GC sweep
 and then allocating a new arena from the system. Neither of these are
-necessary in the infinite memory collector
+necessary in the infinite memory collector.
+
+This function is only used internally to the core, and is not called directly
+from the GC API. Different pools may have special requirements so multiple
+"more_traceable_objects" functions may need to be written and used.
 
 =cut
 
@@ -126,7 +163,14 @@
 
 =item C<void gc_inf_pool_init(PARROT_INTERP, Small_Object_Pool * pool)>
 
-Initializes the function pointers in a new pool
+Initializes the function pointers in a new pool. When a new pool is created
+we assign several function pointers to it for managing memory in the pool.
+In this way we can treat different pools differently if they have special
+management needs. In general all PObj-like pools are treated one way, and
+other pools (such as the pmc_ext pool) are treated differently.
+
+This function is mostly called from the function C<initialize_header_pools>
+in F<src/gc/mark_sweep.c> at Parrot startup.
 
 =cut
 
@@ -145,7 +189,12 @@
 
 =item C<void Parrot_gc_inf_init(PARROT_INTERP)>
 
-Initializes the infinite memory collector
+Initializes the infinite memory collector. Installs the necessary function
+pointers into the Arenas structure. The two most important are the
+C<mark_and_sweep> and C<pool_init> functions. C<finalize_gc_system> function
+will be called at Parrot exit and will shut down the GC system if things
+need to be flushed/closed/deactivated/freed/etc. It can be set to NULL if no
+finalization is necessary.
 
 =cut
 


More information about the parrot-commits mailing list