Base class for OpenAlias/Model debugging utilities.

Synopsis

#include <AlDebug.h>
class AlDebug
static statusCode    cleanUpUniverse( void );
static statusCode     applyIteratorToValid( AlIterator*, int& );
static statusCode    applyIteratorToInvalid( AlIterator*, int& );
static statusCode    applyIteratorToAll( AlIterator*, int& );
static statusCode    outputWrapperUsage( AlOutputType );
static statusCode    setErrorReportingFunction( AlErrorReporter* );
static void    checkpoint( void );

Description

This class provides a set of routines which may help in debugging Alias API applications and plug-ins. Most of these functions are intended for debugging purposes only and should not be used in a release product.

These methods can only be used to debug a single plugin module (if multiple plugins are used, then debugging information will be printed for ALL of the wrappers that have been created or deleted).

The cleanUpUniverse method provides a way to delete all of the wrappers that have not been deleted. It may be possible to use this method in an OpenModel application if no wrappers are created on the user stack.

The applyIterator methods apply an iterator to every wrapper that is created (or that is possibly invalid).

The setErrorReportingFunction method sets the function that is used to display errors.

The following assertion condition macros output errors to stderr before Alias exits:

• AL_ASSERT(condition,msg) - prints out ‘msg’ if the condition fails
• AL_CREATED() - prints out any error message created twice (if the AlObject has already been created)
• AL_NOT_CREATED() - if the object has not been created, an error is printed
• AL_CASE_ERR(caseValue, msg) - used to print out an error ‘msg’ if an unknown case value is detected in a switch statement
• AL_ELSE_ERR() - used to print out an error message if an impossible ’else’ branch is reached
• AL_MEMERR() - prints out a memory error
• AL_ASSERT_COND(condition) - if the given condition fails, then an assertion error message is printed

void AlDebug::checkpoint( void )

Description

Lets you set a breakpoint at a certain point in Alias.

Debugging the initialization of plugins is difficult because the plugin executable is not present until it is loaded.

To use the checkpoint facility, use your debugger to place a breakpoint at the AlDebug::checkpoint function and make an explicit call to this function in the startup code of the plugin. This will allow you to stop your plugin before it begins to fully execute. Note that static initializers will have already been executed by the time the plugin reaches the breakpoint.

statusCode AlDebug::cleanUpUniverse()

Description

Deletes all wrappers that have become invalid.

Note that this method could cause core dumps if not used properly. For example, there will be a core dump if this method is called when there are any invalid objects allocated on the stack. Your application will core dump if it references any pointers to invalid objects after this method is called. If you call this method from OpenAlias, you may invalidate memory belonging to other plugins’ wrappers.

In general, to be safe, never allocate wrappers on the stack, and always assume all pointers are gone after this method is used.

Return Codes

sSuccess - the universe was properly cleaned up

statusCode AlDebug::applyIteratorToValid( AlIterator* iter, int& rc )

Description

Applies the iterator to every valid wrapper that has been created. The return code of the iterator is placed into the variable ’rc’. This routine should only be called when no other plugins are present and all wrappers have been allocated using the ’new’ operator. The behavior of this function is undefined for wrappers which have been allocated on the user stack.

Return Codes

sSuccess - the iterator was applied to every valid wrapper

sFailure - the universe has not been initialized

sInvalidArgument - the given iterator was NULL

statusCode AlDebug::applyIteratorToInvalid( AlIterator* iter, int& rc )

Description

Applies the iterator to every deleted or invalid wrapper. The return code of the iterator is placed into the variable ’rc’. This routine should only be called when no other plugins are present and all wrappers have been allocated using the ’new’ operator. The behavior of this function is undefined for wrappers which have been allocated on the user stack and then deleted.

Return Codes

sSuccess - the iterator was applied to every valid wrapper

sFailure - the universe has not been initialized

sInvalidArgument - the given iterator was NULL

statusCode AlDebug::applyIteratorToAll( AlIterator* iter, int& rc )

Description

Applies the iterator to all valid and invalid wrappers. The return code of the iterator is placed into the variable ’rc’.

Return Codes

sSuccess - the iterator was applied to every valid wrapper

sFailure - the universe has not been initialized

sInvalidArgument - the given iterator was NULL

int AlDebugOutputIterator::func( AlObject* obj )

Description

Applies the iterator to the AlObject. This is an internal routine.

statusCode AlDebug::outputWrapperUsage( AlOutputType tp )

Description

Outputs information about the current wrapper usage. Note that this function can only be called when no other plugins are in use. For every wrapper (either valid or invalid), the object’s address, its type and its name are printed out to the indicated output type.

Return Codes

sSuccess - the iterator was applied to every valid wrapper

sFailure - the universe has not been initialized

sInvalidArgument - the given iterator was NULL

statusCode AlDebug::setErrorReportingFunction( AlErrorReporter* rep )

Description

Sets the callback function that is used to report errors. The current error reporting function is replaced with the given function. The supplied pointer ’rep’ should point to a user-defined ’printf’ style function. (See stdarg.h for more information on parsing the arguments.) This method is only available in OpenModel.

Return Codes

sSuccess - the error reporting function was set

sFailure - OpenAlias is currently being used