gc.h

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

/* 
 * Copyright 1988, 1989 Hans-J. Boehm, Alan J. Demers
 * Copyright (c) 1991-1995 by Xerox Corporation.  All rights reserved.
 * Copyright 1996-1999 by Silicon Graphics.  All rights reserved.
 * Copyright 1999 by Hewlett-Packard Company.  All rights reserved.
 * Copyright (C) 2007 Free Software Foundation, Inc
 *
 * THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
 * OR IMPLIED.  ANY USE IS AT YOUR OWN RISK.
 *
 * Permission is hereby granted to use or copy this program
 * for any purpose,  provided the above notices are retained on all copies.
 * Permission to modify the code and to distribute modified code is granted,
 * provided the above notices are retained, and a notice that the code was
 * modified is included with the above copyright notice.
 */

/*
 * Note that this defines a large number of tuning hooks, which can
 * safely be ignored in nearly all cases.  For normal use it suffices
 * to call only GC_MALLOC and perhaps GC_REALLOC.
 * For better performance, also look at GC_MALLOC_ATOMIC, and
 * GC_enable_incremental.  If you need an action to be performed
 * immediately before an object is collected, look at GC_register_finalizer.
 * If you are using Solaris threads, look at the end of this file.
 * Everything else is best ignored unless you encounter performance
 * problems.
 */
 
#ifndef _GC_H

# define _GC_H

# include "gc_config_macros.h"

# ifdef __cplusplus
    extern "C" {
# endif


/* Define word and signed_word to be unsigned and signed types of the 	*/
/* size as char * or void *.  There seems to be no way to do this	*/
/* even semi-portably.  The following is probably no better/worse 	*/
/* than almost anything else.						*/
/* The ANSI standard suggests that size_t and ptr_diff_t might be 	*/
/* better choices.  But those had incorrect definitions on some older	*/
/* systems.  Notably "typedef int size_t" is WRONG.			*/
#ifndef _WIN64
  typedef unsigned long GC_word;
  typedef long GC_signed_word;
#else
  /* Win64 isn't really supported yet, but this is the first step. And	*/
  /* it might cause error messages to show up in more plausible places.	*/
  /* This needs basetsd.h, which is included by windows.h.	 	*/
  typedef unsigned long long GC_word;
  typedef long long GC_signed_word;
#endif

/* Public read-only variables */

GC_API GC_word GC_gc_no;/* Counter incremented per collection.  	*/
			/* Includes empty GCs at startup.		*/

GC_API int GC_parallel;	/* GC is parallelized for performance on	*/
			/* multiprocessors.  Currently set only		*/
			/* implicitly if collector is built with	*/
			/* -DPARALLEL_MARK and if either:		*/
			/*  Env variable GC_NPROC is set to > 1, or	*/
			/*  GC_NPROC is not set and this is an MP.	*/
			/* If GC_parallel is set, incremental		*/
			/* collection is only partially functional,	*/
			/* and may not be desirable.			*/
			

/* Public R/W variables */

GC_API void * (*GC_oom_fn) (size_t bytes_requested);
			/* When there is insufficient memory to satisfy */
			/* an allocation request, we return		*/
			/* (*GC_oom_fn)().  By default this just	*/
			/* returns 0.					*/
			/* If it returns, it must return 0 or a valid	*/
			/* pointer to a previously allocated heap 	*/
			/* object.					*/

GC_API int GC_find_leak;
			/* Do not actually garbage collect, but simply	*/
			/* report inaccessible memory that was not	*/
			/* deallocated with GC_free.  Initial value	*/
			/* is determined by FIND_LEAK macro.		*/

GC_API int GC_all_interior_pointers;
			/* Arrange for pointers to object interiors to	*/
			/* be recognized as valid.  May not be changed	*/
			/* after GC initialization.			*/
			/* Initial value is determined by 		*/
			/* -DALL_INTERIOR_POINTERS.			*/
			/* Unless DONT_ADD_BYTE_AT_END is defined, this	*/
			/* also affects whether sizes are increased by	*/
			/* at least a byte to allow "off the end"	*/
			/* pointer recognition.				*/
			/* MUST BE 0 or 1.				*/

GC_API int GC_finalize_on_demand;
			/* If nonzero, finalizers will only be run in 	*/
			/* response to an explicit GC_invoke_finalizers	*/
			/* call.  The default is determined by whether	*/
			/* the FINALIZE_ON_DEMAND macro is defined	*/
			/* when the collector is built.			*/

GC_API int GC_java_finalization;
			/* Mark objects reachable from finalizable 	*/
			/* objects in a separate postpass.  This makes	*/
			/* it a bit safer to use non-topologically-	*/
			/* ordered finalization.  Default value is	*/
			/* determined by JAVA_FINALIZATION macro.	*/
			/* Enables register_finalizer_unreachable to	*/
			/* work correctly.				*/

GC_API void (* GC_finalizer_notifier)(void);
			/* Invoked by the collector when there are 	*/
			/* objects to be finalized.  Invoked at most	*/
			/* once per GC cycle.  Never invoked unless 	*/
			/* GC_finalize_on_demand is set.		*/
			/* Typically this will notify a finalization	*/
			/* thread, which will call GC_invoke_finalizers */
			/* in response.					*/

GC_API int GC_dont_gc;	/* != 0 ==> Dont collect.  In versions 6.2a1+,	*/
			/* this overrides explicit GC_gcollect() calls.	*/
			/* Used as a counter, so that nested enabling	*/
			/* and disabling work correctly.  Should	*/
			/* normally be updated with GC_enable() and	*/
			/* GC_disable() calls.				*/
			/* Direct assignment to GC_dont_gc is 		*/
			/* deprecated.					*/

GC_API int GC_dont_expand;
			/* Dont expand heap unless explicitly requested */
			/* or forced to.				*/

GC_API int GC_use_entire_heap;
		/* Causes the nonincremental collector to use the	*/
		/* entire heap before collecting.  This was the only 	*/
		/* option for GC versions < 5.0.  This sometimes	*/
		/* results in more large block fragmentation, since	*/
		/* very larg blocks will tend to get broken up		*/
		/* during each GC cycle.  It is likely to result in a	*/
		/* larger working set, but lower collection		*/
		/* frequencies, and hence fewer instructions executed	*/
		/* in the collector.					*/

GC_API int GC_full_freq;    /* Number of partial collections between	*/
			    /* full collections.  Matters only if	*/
			    /* GC_incremental is set.			*/
			    /* Full collections are also triggered if	*/
			    /* the collector detects a substantial	*/
			    /* increase in the number of in-use heap	*/
			    /* blocks.  Values in the tens are now	*/
			    /* perfectly reasonable, unlike for		*/
			    /* earlier GC versions.			*/
			
GC_API GC_word GC_non_gc_bytes;
			/* Bytes not considered candidates for collection. */
			/* Used only to control scheduling of collections. */
			/* Updated by GC_malloc_uncollectable and GC_free. */
			/* Wizards only.				   */

GC_API int GC_no_dls;
			/* Don't register dynamic library data segments. */
			/* Wizards only.  Should be used only if the	 */
			/* application explicitly registers all roots.	 */
			/* In Microsoft Windows environments, this will	 */
			/* usually also prevent registration of the	 */
			/* main data segment as part of the root set.	 */

GC_API GC_word GC_free_space_divisor;
			/* We try to make sure that we allocate at 	*/
			/* least N/GC_free_space_divisor bytes between	*/
			/* collections, where N is twice the number	*/
			/* of traced bytes, plus the number of untraced */
			/* bytes (bytes in "atomic" objects), plus	*/
			/* a rough estimate of the root set size.	*/
			/* N approximates GC tracing work per GC.	*/
			/* Initially, GC_free_space_divisor = 3.	*/
			/* Increasing its value will use less space	*/
			/* but more collection time.  Decreasing it	*/
			/* will appreciably decrease collection time	*/
			/* at the expense of space.			*/

GC_API GC_word GC_max_retries;
			/* The maximum number of GCs attempted before	*/
			/* reporting out of memory after heap		*/
			/* expansion fails.  Initially 0.		*/
			

GC_API char *GC_stackbottom;    /* Cool end of user stack.		*/
				/* May be set in the client prior to	*/
				/* calling any GC_ routines.  This	*/
				/* avoids some overhead, and 		*/
				/* potentially some signals that can 	*/
				/* confuse debuggers.  Otherwise the	*/
				/* collector attempts to set it 	*/
				/* automatically.			*/
				/* For multithreaded code, this is the	*/
				/* cold end of the stack for the	*/
				/* primordial thread.			*/	
				
GC_API int GC_dont_precollect;  /* Don't collect as part of 		*/
				/* initialization.  Should be set only	*/
				/* if the client wants a chance to	*/
				/* manually initialize the root set	*/
				/* before the first collection.		*/
				/* Interferes with blacklisting.	*/
				/* Wizards only.			*/

GC_API unsigned long GC_time_limit;
				/* If incremental collection is enabled, */
				/* We try to terminate collections	 */
				/* after this many milliseconds.  Not a	 */
				/* hard time bound.  Setting this to 	 */
				/* GC_TIME_UNLIMITED will essentially	 */
				/* disable incremental collection while  */
				/* leaving generational collection	 */
				/* enabled.	 			 */
#	define GC_TIME_UNLIMITED 999999
				/* Setting GC_time_limit to this value	 */
				/* will disable the "pause time exceeded"*/
				/* tests.				 */

/* Public procedures */

/* Initialize the collector.  This is only required when using thread-local
 * allocation, since unlike the regular allocation routines, GC_local_malloc
 * is not self-initializing.  If you use GC_local_malloc you should arrange
 * to call this somehow (e.g. from a constructor) before doing any allocation.
 * For win32 threads, it needs to be called explicitly.
 */
GC_API void GC_init(void);

/*
 * general purpose allocation routines, with roughly malloc calling conv.
 * The atomic versions promise that no relevant pointers are contained
 * in the object.  The nonatomic versions guarantee that the new object
 * is cleared.  GC_malloc_stubborn promises that no changes to the object
 * will occur after GC_end_stubborn_change has been called on the
 * result of GC_malloc_stubborn. GC_malloc_uncollectable allocates an object
 * that is scanned for pointers to collectable objects, but is not itself
 * collectable.  The object is scanned even if it does not appear to
 * be reachable.  GC_malloc_uncollectable and GC_free called on the resulting
 * object implicitly update GC_non_gc_bytes appropriately.
 *
 * Note that the GC_malloc_stubborn support is stubbed out by default
 * starting in 6.0.  GC_malloc_stubborn is an alias for GC_malloc unless
 * the collector is built with STUBBORN_ALLOC defined.
 */
GC_API void * GC_malloc(size_t size_in_bytes);
GC_API void * GC_malloc_atomic(size_t size_in_bytes);
GC_API char * GC_strdup (const char *str);
GC_API void * GC_malloc_uncollectable(size_t size_in_bytes);
GC_API void * GC_malloc_stubborn(size_t size_in_bytes);

/* The following is only defined if the library has been suitably	*/
/* compiled:								*/
GC_API void * GC_malloc_atomic_uncollectable(size_t size_in_bytes);

/* Explicitly deallocate an object.  Dangerous if used incorrectly.     */
/* Requires a pointer to the base of an object.				*/
/* If the argument is stubborn, it should not be changeable when freed. */
/* An object should not be enable for finalization when it is 		*/
/* explicitly deallocated.						*/
/* GC_free(0) is a no-op, as required by ANSI C for free.		*/
GC_API void GC_free(void * object_addr);

/*
 * Stubborn objects may be changed only if the collector is explicitly informed.
 * The collector is implicitly informed of coming change when such
 * an object is first allocated.  The following routines inform the
 * collector that an object will no longer be changed, or that it will
 * once again be changed.  Only nonNIL pointer stores into the object
 * are considered to be changes.  The argument to GC_end_stubborn_change
 * must be exacly the value returned by GC_malloc_stubborn or passed to
 * GC_change_stubborn.  (In the second case it may be an interior pointer
 * within 512 bytes of the beginning of the objects.)
 * There is a performance penalty for allowing more than