gc.h

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

 * one stubborn object to be changed at once, but it is acceptable to
 * do so.  The same applies to dropping stubborn objects that are still
 * changeable.
 */
GC_API void GC_change_stubborn(void *);
GC_API void GC_end_stubborn_change(void *);

/* Return a pointer to the base (lowest address) of an object given	*/
/* a pointer to a location within the object.				*/
/* I.e. map an interior pointer to the corresponding bas pointer.	*/
/* Note that with debugging allocation, this returns a pointer to the	*/
/* actual base of the object, i.e. the debug information, not to	*/
/* the base of the user object.						*/
/* Return 0 if displaced_pointer doesn't point to within a valid	*/
/* object.								*/
/* Note that a deallocated object in the garbage collected heap		*/
/* may be considered valid, even if it has been deallocated with	*/
/* GC_free.								*/
GC_API void * GC_base(void * displaced_pointer);

/* Given a pointer to the base of an object, return its size in bytes.	*/
/* The returned size may be slightly larger than what was originally	*/
/* requested.								*/
GC_API size_t GC_size(void * object_addr);

/* For compatibility with C library.  This is occasionally faster than	*/
/* a malloc followed by a bcopy.  But if you rely on that, either here	*/
/* or with the standard C library, your code is broken.  In my		*/
/* opinion, it shouldn't have been invented, but now we're stuck. -HB	*/
/* The resulting object has the same kind as the original.		*/
/* If the argument is stubborn, the result will have changes enabled.	*/
/* It is an error to have changes enabled for the original object.	*/
/* Follows ANSI comventions for NULL old_object.			*/
GC_API void * GC_realloc(void * old_object, size_t new_size_in_bytes);
				   
/* Explicitly increase the heap size.	*/
/* Returns 0 on failure, 1 on success.  */
GC_API int GC_expand_hp(size_t number_of_bytes);

/* Limit the heap size to n bytes.  Useful when you're debugging, 	*/
/* especially on systems that don't handle running out of memory well.	*/
/* n == 0 ==> unbounded.  This is the default.				*/
GC_API void GC_set_max_heap_size(GC_word n);

/* Inform the collector that a certain section of statically allocated	*/
/* memory contains no pointers to garbage collected memory.  Thus it 	*/
/* need not be scanned.  This is sometimes important if the application */
/* maps large read/write files into the address space, which could be	*/
/* mistaken for dynamic library data segments on some systems.		*/
GC_API void GC_exclude_static_roots(void * low_address,
				    void * high_address_plus_1);

/* Clear the set of root segments.  Wizards only. */
GC_API void GC_clear_roots(void);

/* Add a root segment.  Wizards only. */
GC_API void GC_add_roots(void * low_address, void * high_address_plus_1);

/* Remove a root segment.  Wizards only. */
GC_API void GC_remove_roots(void * low_address, void * high_address_plus_1);

/* Add a displacement to the set of those considered valid by the	*/
/* collector.  GC_register_displacement(n) means that if p was returned */
/* by GC_malloc, then (char *)p + n will be considered to be a valid	*/
/* pointer to p.  N must be small and less than the size of p.		*/
/* (All pointers to the interior of objects from the stack are		*/
/* considered valid in any case.  This applies to heap objects and	*/
/* static data.)							*/
/* Preferably, this should be called before any other GC procedures.	*/
/* Calling it later adds to the probability of excess memory		*/
/* retention.								*/
/* This is a no-op if the collector has recognition of			*/
/* arbitrary interior pointers enabled, which is now the default.	*/
GC_API void GC_register_displacement(size_t n);

/* The following version should be used if any debugging allocation is	*/
/* being done.								*/
GC_API void GC_debug_register_displacement(size_t n);

/* Explicitly trigger a full, world-stop collection. 	*/
GC_API void GC_gcollect(void);

/* Trigger a full world-stopped collection.  Abort the collection if 	*/
/* and when stop_func returns a nonzero value.  Stop_func will be 	*/
/* called frequently, and should be reasonably fast.  This works even	*/
/* if virtual dirty bits, and hence incremental collection is not 	*/
/* available for this architecture.  Collections can be aborted faster	*/
/* than normal pause times for incremental collection.  However,	*/
/* aborted collections do no useful work; the next collection needs	*/
/* to start from the beginning.						*/
/* Return 0 if the collection was aborted, 1 if it succeeded.		*/
typedef int (* GC_stop_func)(void);
GC_API int GC_try_to_collect(GC_stop_func stop_func);

/* Return the number of bytes in the heap.  Excludes collector private	*/
/* data structures.  Includes empty blocks and fragmentation loss.	*/
/* Includes some pages that were allocated but never written.		*/
GC_API size_t GC_get_heap_size(void);

/* Return a lower bound on the number of free bytes in the heap.	*/
GC_API size_t GC_get_free_bytes(void);

/* Return the number of bytes allocated since the last collection.	*/
GC_API size_t GC_get_bytes_since_gc(void);

/* Return the total number of bytes allocated in this process.		*/
/* Never decreases, except due to wrapping.				*/
GC_API size_t GC_get_total_bytes(void);

/* Disable garbage collection.  Even GC_gcollect calls will be 		*/
/* ineffective.								*/
GC_API void GC_disable(void);

/* Reenable garbage collection.  GC_disable() and GC_enable() calls 	*/
/* nest.  Garbage collection is enabled if the number of calls to both	*/
/* both functions is equal.						*/
GC_API void GC_enable(void);

/* Enable incremental/generational collection.	*/
/* Not advisable unless dirty bits are 		*/
/* available or most heap objects are		*/
/* pointerfree(atomic) or immutable.		*/
/* Don't use in leak finding mode.		*/
/* Ignored if GC_dont_gc is true.		*/
/* Only the generational piece of this is	*/
/* functional if GC_parallel is TRUE		*/
/* or if GC_time_limit is GC_TIME_UNLIMITED.	*/
/* Causes GC_local_gcj_malloc() to revert to	*/
/* locked allocation.  Must be called 		*/
/* before any GC_local_gcj_malloc() calls.	*/
/* For best performance, should be called as early as possible.	*/
/* On some platforms, calling it later may have adverse effects.*/
/* Safe to call before GC_INIT().  Includes a GC_init() call.	*/
GC_API void GC_enable_incremental(void);

/* Does incremental mode write-protect pages?  Returns zero or	*/
/* more of the following, or'ed together:			*/
#define GC_PROTECTS_POINTER_HEAP  1 /* May protect non-atomic objs.	*/
#define GC_PROTECTS_PTRFREE_HEAP  2
#define GC_PROTECTS_STATIC_DATA   4 /* Currently never.			*/
#define GC_PROTECTS_STACK	  8 /* Probably impractical.		*/

#define GC_PROTECTS_NONE 0
GC_API int GC_incremental_protection_needs(void);

/* Perform some garbage collection work, if appropriate.	*/
/* Return 0 if there is no more work to be done.		*/
/* Typically performs an amount of work corresponding roughly	*/
/* to marking from one page.  May do more work if further	*/
/* progress requires it, e.g. if incremental collection is	*/
/* disabled.  It is reasonable to call this in a wait loop	*/
/* until it returns 0.						*/
GC_API int GC_collect_a_little(void);

/* Allocate an object of size lb bytes.  The client guarantees that	*/
/* as long as the object is live, it will be referenced by a pointer	*/
/* that points to somewhere within the first 256 bytes of the object.	*/
/* (This should normally be declared volatile to prevent the compiler	*/
/* from invalidating this assertion.)  This routine is only useful	*/
/* if a large array is being allocated.  It reduces the chance of 	*/
/* accidentally retaining such an array as a result of scanning an	*/
/* integer that happens to be an address inside the array.  (Actually,	*/
/* it reduces the chance of the allocator not finding space for such	*/
/* an array, since it will try hard to avoid introducing such a false	*/
/* reference.)  On a SunOS 4.X or MS Windows system this is recommended */
/* for arrays likely to be larger than 100K or so.  For other systems,	*/
/* or if the collector is not configured to recognize all interior	*/
/* pointers, the threshold is normally much higher.			*/
GC_API void * GC_malloc_ignore_off_page(size_t lb);
GC_API void * GC_malloc_atomic_ignore_off_page(size_t lb);

#if defined(__sgi) && !defined(__GNUC__) && _COMPILER_VERSION >= 720
#   define GC_ADD_CALLER
#   define GC_RETURN_ADDR (GC_word)__return_address
#endif

#if defined(__linux__) || defined(__GLIBC__)
# include <features.h>
# if (__GLIBC__ == 2 && __GLIBC_MINOR__ >= 1 || __GLIBC__ > 2) \
     && !defined(__ia64__)
#   ifndef GC_HAVE_BUILTIN_BACKTRACE
#     define GC_HAVE_BUILTIN_BACKTRACE
#   endif
# endif
# if defined(__i386__) || defined(__x86_64__)
#   define GC_CAN_SAVE_CALL_STACKS
# endif
#endif

#if defined(_MSC_VER) && _MSC_VER >= 1200 /* version 12.0+ (MSVC 6.0+)  */ \
    && !defined(_AMD64_)
# ifndef GC_HAVE_NO_BUILTIN_BACKTRACE
#   define GC_HAVE_BUILTIN_BACKTRACE
# endif
#endif

#if defined(GC_HAVE_BUILTIN_BACKTRACE) && !defined(GC_CAN_SAVE_CALL_STACKS)
# define GC_CAN_SAVE_CALL_STACKS
#endif

#if defined(__sparc__)
#   define GC_CAN_SAVE_CALL_STACKS
#endif

/* If we're on an a platform on which we can't save call stacks, but	*/
/* gcc is normally used, we go ahead and define GC_ADD_CALLER.  	*/
/* We make this decision independent of whether gcc is actually being	*/
/* used, in order to keep the interface consistent, and allow mixing	*/
/* of compilers.							*/
/* This may also be desirable if it is possible but expensive to	*/
/* retrieve the call chain.						*/
#if (defined(__linux__) || defined(__NetBSD__) || defined(__OpenBSD__) \
     || defined(__FreeBSD__) || defined(__DragonFly__)) & !defined(GC_CAN_SAVE_CALL_STACKS)
# define GC_ADD_CALLER
# if __GNUC__ >= 3 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 95) 
    /* gcc knows how to retrieve return address, but we don't know */
    /* how to generate call stacks.				   */
#   define GC_RETURN_ADDR (GC_word)__builtin_return_address(0)
# else
    /* Just pass 0 for gcc compatibility. */
#   define GC_RETURN_ADDR 0
# endif
#endif

#ifdef GC_ADD_CALLER
#  define GC_EXTRAS GC_RETURN_ADDR, __FILE__, __LINE__
#  define GC_EXTRA_PARAMS GC_word ra, const char * s, int i
#else
#  define GC_EXTRAS __FILE__, __LINE__
#  define GC_EXTRA_PARAMS const char * s, int i
#endif

/* Debugging (annotated) allocation.  GC_gcollect will check 		*/
/* objects allocated in this way for overwrites, etc.			*/
GC_API void * GC_debug_malloc(size_t size_in_bytes, GC_EXTRA_PARAMS);
GC_API void * GC_debug_malloc_atomic(size_t size_in_bytes, GC_EXTRA_PARAMS);
GC_API char * GC_debug_strdup(const char *str, GC_EXTRA_PARAMS);
GC_API void * GC_debug_malloc_uncollectable
	(size_t size_in_bytes, GC_EXTRA_PARAMS);
GC_API void * GC_debug_malloc_stubborn
	(size_t size_in_bytes, GC_EXTRA_PARAMS);
GC_API void * GC_debug_malloc_ignore_off_page
	(size_t size_in_bytes, GC_EXTRA_PARAMS);
GC_API void * GC_debug_malloc_atomic_ignore_off_page
	(size_t size_in_bytes, GC_EXTRA_PARAMS);
GC_API void GC_debug_free (void * object_addr);
GC_API void * GC_debug_realloc
	(void * old_object, size_t new_size_in_bytes, GC_EXTRA_PARAMS);
GC_API void GC_debug_change_stubborn(void *);
GC_API void GC_debug_end_stubborn_change(void *);

/* Routines that allocate objects with debug information (like the 	*/
/* above), but just fill in dummy file and line number information.	*/
/* Thus they can serve as drop-in malloc/realloc replacements.  This	*/
/* can be useful for two reasons:  					*/
/* 1) It allows the collector to be built with DBG_HDRS_ALL defined	*/
/*    even if some allocation calls come from 3rd party libraries	*/
/*    that can't be recompiled.						*/
/* 2) On some platforms, the file and line information is redundant,	*/
/*    since it can be reconstructed from a stack trace.  On such	*/
/*    platforms it may be more convenient not to recompile, e.g. for	*/
/*    leak detection.  This can be accomplished by instructing the	*/
/*    linker to replace malloc/realloc with these.			*/
GC_API void * GC_debug_malloc_replacement (size_t size_in_bytes);
GC_API void * GC_debug_realloc_replacement
	      (void * object_addr, size_t size_in_bytes);
  			 	 
# ifdef GC_DEBUG
#   define GC_MALLOC(sz) GC_debug_malloc(sz, GC_EXTRAS)
#   define GC_MALLOC_ATOMIC(sz) GC_debug_malloc_atomic(sz, GC_EXTRAS)
#   define GC_STRDUP(s) GC_debug_strdup((s), GC_EXTRAS)
#   define GC_MALLOC_UNCOLLECTABLE(sz) \
			GC_debug_malloc_uncollectable(sz, GC_EXTRAS)
#   define GC_MALLOC_IGNORE_OFF_PAGE(sz) \
			GC_debug_malloc_ignore_off_page(sz, GC_EXTRAS)
#   define GC_MALLOC_ATOMIC_IGNORE_OFF_PAGE(sz) \
			GC_debug_malloc_atomic_ignore_off_page(sz, GC_EXTRAS)
#   define GC_REALLOC(old, sz) GC_debug_realloc(old, sz, GC_EXTRAS)
#   define GC_FREE(p) GC_debug_free(p)
#   define GC_REGISTER_FINALIZER(p, f, d, of, od) \
	GC_debug_register_finalizer(p, f, d, of, od)
#   define GC_REGISTER_FINALIZER_IGNORE_SELF(p, f, d, of, od) \
	GC_debug_register_finalizer_ignore_self(p, f, d, of, od)
#   define GC_REGISTER_FINALIZER_NO_ORDER(p, f, d, of, od) \
	GC_debug_register_finalizer_no_order(p, f, d, of, od)