BlitzMax Extended  0.8.11
Pushing Blitz to the Max.
Defines | 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.

Defines

#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  BBGCAllocFlags { BBGC_DEFAULT, BBGC_ATOMIC, BBGC_FINALIZE }
 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.
BBObjectbbGCAllocObject (BBSize size, const BBClass *clas, BBInt flags)
 Allocates a new object managed by 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

Define 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.
Enumerator:
BBGC_DEFAULT 
  
BBGC_ATOMIC 
  
BBGC_FINALIZE 
  
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

BBObject* bbGCAllocObject ( BBSize  size,
const BBClass clas,
BBInt  flags 
)

Allocates a new object managed by the GC.

Parameters:
sizeThe size of the instance to be allocated
clasThe new instance's class
flagsModifying allocation/deallocation of the new instance
Returns:
A new instance of the given class. In case of an error NULL is returned.

Referenced by bbObjectNew().

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(), and bbMemAlloc().

Gets the GC's operating mode.

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

Referenced by bbGCGetMode().

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.

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().