Debugging
[Console]

Functionality to help spot program errors. More...

Functions
void	backtrace ()
	Prints the scripting call stack to the console log.
void	debug ()
	Drops the engine into the native C++ debugger.
void	debugDumpAllObjects ()
	Dumps all current EngineObject instances to the console.
void	debugv (string variableName)
	Logs the value of the given variable to the console.
void	dumpAlloc (int allocNum)
	Dumps information about the given allocated memory block.
void	dumpMemSnapshot (string fileName)
	Dumps a snapshot of current memory to a file.
void	dumpUnflaggedAllocs (string fileName="")
	Dumps all unflagged memory allocations.
void	flagCurrentAllocs ()
	Flags all current memory allocations.
void	freeMemoryDump ()
	Dumps some useful statistics regarding free memory.
void	profilerDump ()
	Dumps current profiling stats to the console window.
void	profilerDumpToFile (string fileName)
	Dumps current profiling stats to a file.
void	profilerEnable (bool enable)
	Enables or disables the profiler.
void	profilerMarkerEnable (string markerName, bool enable=true)
	Enable or disable a specific profile.
void	profilerReset ()
	Resets the profiler, clearing it of all its data.
int	sizeof (string objectOrClass)
	Determines the memory consumption of a class or object.
void	telnetSetParameters (int port, string consolePass, string listenPass, bool remoteEcho=false)
	Initializes and open the telnet console.
void	trace (bool enable=true)
	Enable or disable tracing in the script code VM.
void	validateMemory ()
	Used to validate memory space for the game.
Variables
string	getBuildString
	Get the type of build, "Debug" or "Release".
string	getCompileTimeString
	Get the time of compilation.
string	getEngineName
	Get the name of the engine product that this is running from, as a string.
int	getVersionNumber
	Get the version of the build, as a string.
string	getVersionString
	Get the version of the build, as a string.

Detailed Description

Functionality to help spot program errors.

Also provides profiler functions, helpful in determining performance bottlenecks.

Function Documentation

void backtrace ( )

Prints the scripting call stack to the console log.

Used to trace functions called from within functions. Can help discover what functions were called (and not yet exited) before the current point in scripts.

void debug ( )

Drops the engine into the native C++ debugger.

This function triggers a debug break and drops the process into the IDE's debugger. If the process is not running with a debugger attached it will generate a runtime error on most platforms.

Note:: This function is not available in shipping builds.

void debugDumpAllObjects ( )

Dumps all current EngineObject instances to the console.

Note:: This function is only available in debug builds.

void debugv ( string variableName )

Logs the value of the given variable to the console.

Prints a string of the form "<variableName> = <variable value>" to the console.

Parameters:

variableName

Name of the local or global variable to print.

Example:

%var = 1;
debugv( "%var" ); // Prints "%var = 1"

void dumpAlloc ( int allocNum )

Dumps information about the given allocated memory block.

Parameters:

allocNum

Memory block to dump information about.

Note:: Available in debug builds only. In torqueConfig.h, TORQUE_DISABLE_MEMORY_MANAGER must be undefined to use this function.

void dumpMemSnapshot ( string fileName )

Dumps a snapshot of current memory to a file.

The total memory used will also be output to the console. This function will attempt to create the file if it does not already exist.

Parameters:

fileName

Name and path of file to save profiling stats to. Must use forward slashes (/)

Example:

dumpMemSnapshot( "C:/Torque/ProfilerLogs/profilerlog1.txt" );

Note:: Available in debug builds only. In torqueConfig.h, TORQUE_DISABLE_MEMORY_MANAGER must be undefined to use this function.

void dumpUnflaggedAllocs ( string fileName = "" )

Dumps all unflagged memory allocations.

Dumps all memory allocations that were made after a call to flagCurrentAllocs(). Helpful when used with flagCurrentAllocs() for detecting memory leaks and analyzing general memory usage.

Parameters:

fileName

Optional file path and location to dump all memory allocations not flagged by flagCurrentAllocs(). If left blank, data will be dumped to the console.

Example:

dumpMemSnapshot(); // dumps info to console
dumpMemSnapshot( "C:/Torque/profilerlog1.txt" ); // dumps info to file

Note:: Available in debug builds only. In torqueConfig.h, TORQUE_DISABLE_MEMORY_MANAGER must be undefined to use this function.

void flagCurrentAllocs ( )

Flags all current memory allocations.

Flags all current memory allocations for exclusion in subsequent calls to dumpUnflaggedAllocs(). Helpful in detecting memory leaks and analyzing memory usage.

void freeMemoryDump ( )

Dumps some useful statistics regarding free memory.

Dumps an analysis of 'free chunks' of memory. Does not print how much memory is free.

void profilerDump ( )

Dumps current profiling stats to the console window.

Note:: Markers disabled with profilerMarkerEnable() will be skipped over. If the profiler is currently running, it will be disabled.

void profilerDumpToFile ( string fileName )

Dumps current profiling stats to a file.

Note:: If the profiler is currently running, it will be disabled.

Parameters:

fileName

Name and path of file to save profiling stats to. Must use forward slashes (/). Will attempt to create the file if it does not already exist.

Example:

profilerDumpToFile( "C:/Torque/log1.txt" );

void profilerEnable ( bool enable )

Enables or disables the profiler.

Data is only gathered while the profiler is enabled.

Note:: Profiler is not available in shipping builds. T3D has predefined profiling areas surrounded by markers, but you may need to define additional markers (in C++) around areas you wish to profile, by using the PROFILE_START( markerName ); and PROFILE_END(); macros.

void profilerMarkerEnable	(	string	markerName,
		bool	enable = `true`
	)

Enable or disable a specific profile.

Parameters:

	enable	Optional paramater to enable or disable the profile.
	markerName	Name of a specific marker to enable or disable.

Note:: Calling this function will first call profilerReset(), clearing all data from profiler. All profile markers are enabled by default.

void profilerReset ( )

Resets the profiler, clearing it of all its data.

If the profiler is currently running, it will first be disabled. All markers will retain their current enabled/disabled status.

int sizeof ( string objectOrClass )

Determines the memory consumption of a class or object.

Parameters:

objectOrClass

The object or class being measured.

Returns:: Returns the total size of an object in bytes.

void telnetSetParameters	(	int	port,
		string	consolePass,
		string	listenPass,
		bool	remoteEcho = `false`
	)

Initializes and open the telnet console.

Parameters:

	port	Port to listen on for console connections (0 will shut down listening).
	consolePass	Password for read/write access to console.
	listenPass	Password for read access to console.
	remoteEcho	[optional] Enable echoing back to the client, off by default.

void trace ( bool enable = true )

Enable or disable tracing in the script code VM.

When enabled, the script code runtime will trace the invocation and returns from all functions that are called and log them to the console. This is helpful in observing the flow of the script program.

Parameters:

enable

New setting for script trace execution, on by default.

void validateMemory ( )

Used to validate memory space for the game.