BlitzMax Extended  0.8.17
Pushing Blitz to the Max.
Macros | Enumerations | Functions
blitz_gc.h File Reference

Interface for the intern garbage collectors. More...

#include "_common.h"

Go to the source code of this file.

Macros

#define BBGC_MAX_SUSPENDED   (BBINT_MAX - 1)
 The maximum number of times the GC can be suspended.

Enumerations

enum  BBGCMode { BBGC_AUTOMATIC = 1, BBGC_MANUAL = 2 }
 Operating modes for the GC. More...
enum  BBGCDebugMode { BBGC_NODEBUG, BBGC_STDOUTDEBUG }
enum  BBGCAllocFlags
 All possible flags affecting the allocation and deallocation of an object with the GC. More...

Functions

BBGCMode bbGCGetMode ()
 Gets the GC's operating mode.
void bbGCSetMode (BBGCMode mode)
 Sets the GC's operating mode.
void bbGCSetDebug (BBGCDebugMode mode)
 Sets the debug mode of the GC.
void * bbGCMalloc (BBInt size, BBInt flags)
 Allocates a block of memory with the GC.
BBBool bbGCValidate (const void *ptr)
 Validates a block of memory.
BBInt bbGCMemAlloced ()
 Gets the amount of memory currently allocated by the GC.
BBInt bbGCCollect ()
 Collects unused memory.
void bbGCSuspend ()
 Suspends the GC's execution.
BBBool bbGCIsSuspended ()
 Checks if the GC is currently suspended.
void bbGCResume ()
 Resumes a suspended GC.

Detailed Description

Interface for the intern garbage collectors.

Garbage collection means that the language takes care of cleaning up and freeing of unused memory. Therefore you don't usually call destructors in BlitzMax. The GC (Garbage Collector) takes care of this for you.

In case you need to manually handle your objects you can also halt the GC's execution via bbGCSuspend.

You will notice that there are two different GC's included in BlitzMax. The one found in "blitz_gc_rc.c" is a reference-counting GC. It is used in single threaded mode of BlitzMax. You will work with this one most of the time.

For multi-threaded applications a different approach is needed. The "Mark Sibly GC" found in "blitz_gc_ms.c" is capable of cyclic references and multi-threading and is therefore used in threaded building mode.

Author:
Mark Sibly

Macro Definition Documentation

#define BBGC_MAX_SUSPENDED   (BBINT_MAX - 1)

The maximum number of times the GC can be suspended.

It's "-1" because the ref-counting GC's bbGCCollect increases the count by one at the beginning and resets it later. This value prevents an overflow.

Referenced by bbGCSuspend().


Enumeration Type Documentation

All possible flags affecting the allocation and deallocation of an object with the GC.

Note:
At the moment, only the multi-threaded garbage collector is affected by these flags.
See also:
Enumerator:
BBGC_NODEBUG 

Disables the GC debug mode.

This is the default mode.

BBGC_STDOUTDEBUG 

Enables the GC debug mode via stdout.

enum BBGCMode

Operating modes for the GC.

See also:
bbGCGetMode, bbGCSetMode
Enumerator:
BBGC_AUTOMATIC 

Sets the GC to automatic mode.

In automatic mode, unused objects are collected as the GC sees fit.

This is the default mode.

BBGC_MANUAL 

Sets the GC to manual mode.

In manual mode, unused objects won't be collected until bbGCCollect is called manually by the programmer. Hence the name.

See also:
bbGCCollect

Function Documentation

BBInt bbGCCollect ( )

Collects unused memory.

If the GC is suspended, this has no effect.

See also:
bbGCResume
Returns:
The amount of memory collected in bytes.

Referenced by bbGCCollect().

BBGCMode bbGCGetMode ( )

Gets the GC's operating mode.

See also:
BBGCMode
Returns:
The GC's current operating mode.

Referenced by bbGCGetMode().

BBBool bbGCIsSuspended ( )

Checks if the GC is currently suspended.

See also:
bbSuspend, bbGCResume
Return values:
BBTRUEif the GC is currently suspended
BBFALSEif the GC is currently running (not suspended)

Referenced by bbGCIsSuspended().

void* bbGCMalloc ( BBInt  size,
BBInt  flags 
)

Allocates a block of memory with the GC.

Parameters:
sizeThe size of the memory block in bytes
Returns:
A pointer to the newly allocated memory or NULL in case of an error.
BBInt bbGCMemAlloced ( )

Gets the amount of memory currently allocated by the GC.

Returns:
The currently amount of allocated memory.

Referenced by bbGCMemAlloced().

void bbGCResume ( )

Resumes a suspended GC.

After suspending the GC with bbGCSuspend, this resumes its execution. If the GC is already running (not suspended) this has no effect.

To check if the GC is running, use bbGCIsSuspended

See also:
bbGCSuspend, bbGCISSuspended

Referenced by bbGCResume().

void bbGCSetDebug ( BBGCDebugMode  mode)

Sets the debug mode of the GC.

In case the mode parameter is invalid, debug mode is set to BBGC_NODEBUG.

Parameters:
modeThe debug mode of the GC

Referenced by bbGCSetDebug().

void bbGCSetMode ( BBGCMode  mode)

Sets the GC's operating mode.

In case the mode parameter is invalid, operating mode is set to BBGC_AUTOMATIC.

Parameters:
modeThe mode at which the GC should operate

Referenced by bbGCSetMode().

void bbGCSuspend ( )

Suspends the GC's execution.

Temporarily halts the execution of the GC. To keep track of multiple commands to suspend, an internal counter is increased with every call.

Note that this function can only increase the counter up to BBGC_MAX_SUSPENDED without a matching call to bbGCResume. Therefore the limit for the number of supensions is also BBGC_MAX_SUSPENDED. After that all calls to this function have no effect until bbGCResume is called.

Note:
Suspending and resuming are nested. That means that each call to bbGCSuspend must be matched by a call to bbGCResume.
See also:
bbGCResume, bbGCIsSuspended, BBGC_MAX_SUSPENDED

Referenced by bbGCSuspend().

BBBool bbGCValidate ( const void *  ptr)

Validates a block of memory.

Return values:
BBTRUEBBFALSE

Referenced by bbGCValidate().