Defines base logging classes used in the Lazarus IDE.

lazloggerbase.pas contains classes, types, and routines used to implement the base logging mechanisms used in the Lazarus IDE. Its primary usage, when used along with the LazLogger unit, is to provide output to the debugger in the Lazarus IDE.

Logger classes (and routines) are found in units like:

LazLoggerBase.pas
  Provides the base TLazLogger class used as the common ancestor for other logger classes. Use this unit when you want to use the debugln routine. What LazLoggerBase does depends on whether the unit LazLogger is used in any other unit of your application. If LazLogger is not used, LazLoggerBase will install a "blackhole logger" that discards all log messages. If LazLogger is used anywhere, then all units using LazLoggerBase will write the log messages as described under "Logging Output"
LazLogger.pas
  Provides a logger class which writes output to a file or file handle. Use this unit to activate the functionality of LazLogger.
LazLoggerProfiling.pas
  Provides a logger class which captures memory usage and execution times.
LazLoggerDummy.pas
  Re-implements the logger class methods with empty implementations. They are just calls to empty methods. This allows you to disable logging in a unit without the need to remove debugln statements.

The LazLoggerIntf.inc include file contains interface declarations for routines and operators which should be implemented in each of the units for the various loggers.

Usage

Add one of the logger classes to your application to enable output of logging messages to the destination supported in the logger class. By using the LazLogger unit, the following are enabled:

- A single string, or list of (up to 15) strings: DebugLn('Foo'); DbgOut('a','b');
- An array of const: DebugLn(['Foo=', 1, ' Bar=', anInteger]);
- Same arguments as Format(). String + array of const: DbgOut('a %d',[1]);

Also there are tons of dbgs functions that converts common types to a string. For example dbgs(aRect) converts a variable of type TRect to a string.

Logger output

Stdout/Console

  By default the output created by DebugLn is written to the stdout device. The output is silently discarded if stdout is not open. On Windows this is the default behavior, if project type "Application" is used to create a Windows GUI application. To get a console alongside your Windows GUI application, you need to uncheck the option "Win32 gui application (-WG)" under Project options / Compiler options / Config and Target / Target specific options. Alternatively you can add {$APPTYPE CONSOLE} at the top of your project .lpr file, or configure multiple "Build Modes" to control the -WG switch.

File

  Debug output can also be written to file. The initialization code of the logging unit checks your program's command line parameters for --debug-log=<file> (In Lazarus: Run / Run Parameters / Command line parameters). On finding this parameter, any subsequent debug output is sent to <file>.

  The param name can be changed with DebugLogger.ParamForLogFileName:='--debug-log'; This property exists only if the unit LazLogger is used. (LazLoggerBase does not define this property).

  If no '--debug-log' command line parameter has been given, it next checks if an operating system environment variable xxx_debuglog exists, where xxx is the program file name without extension. E.g. for Lazarus this would be lazarus_debuglog. If such an environment variable exists, it uses the file specified in that environment variable as file to receive debug output.

Multithreading

DebugLn is thread safe, since Lazarus 2.0. Earlier versions of this text stated "since 1.0", but a further race condition was found and fixed for 2.0.

Calls to DbgOut, DebugLnEnter, DebugLnExit can be made from threads, but may not always format/indent the output correctly.

The creation/setup/destruction/configuration of the logger is not thread-safe, and should be done before threads are started. Creation is usually done automatically during unit initialization. But any properties (eg ParamForLogFileName) should be set before accessing the logger from threads.

Callback to events like OnDebugLn are made in each thread. The code in the callback must be thread save by itself. Changing the routine assigned to the property is NOT thread-safe.

This file is part of the LazUtils package.

Represents flags used for Log Groups in TLazLogger.
Not added using RegisterLogGroup in the logger class. This is a placeholder for the enabled-state given by the user via the command line.
Registered and enabled without a default group name.
Set type used to store values from the TLazLoggerLogGroupFlag enumeration.

TLazLoggerLogGroupFlags is the type used for the FLags member in TLazLoggerLogGroup.

Record type with information about a log group in TLazLogger.
Case-insensitive name for the log group.
True if the log group is enabled.
Flags which indicate how the log was created, and whether it is active.
Member usesd to track the current indentation level for the log group.
Pointer to a TLazLoggerLogGroup instance.
Record type used to track an enabled log group.
Indicates the destination where output from a logger is written or stored.
Logger output is not written or stored... it is discarded.
Logger output is written to the stdout device.
Logger outout is written to the StdErr device.
Logger output is written to a text file.
Specifies an event handler signalled to write logger output.
Specifies an event handler used to perform widgetset-specific debug log message handling.

TLazLoggerWidgetSetWriteEvent is the type used for the OnWidgetSetDebugLn and OnWidgetSetDbgOut unit variables. Used primarily for the custom-drawn Android widgetset.

Object with the logger class instance (TLazLogger) for the event.
Log message handled in the routine.
True if the message was handled in the routine, False if the default output mechanism for the logger class is used.
Destination where the log message is written.
Optional pointer to data for the log message.
Implements a container for TLazLoggerLogGroup instances.
Creates and adds a new logger group in the container.
Pointer to the TLazLoggerLogGroup instance created and added in the method.
Case-insensitive name for the log group added in the method.
True if enabled by default.
Finds or creates a log group in the container with the specified name and enabled status.
Pointer to the TLazLoggerLogGroup instance with the specified name.
Name of the log group to locate or create in the container.
Default enabled status if the log group is created.
Removes a log group from the container.

Remove is overloaded to allow the group to be located using a pointer to the TLazLoggerLogGroup entry, or by a specified name. Remove calls Dispose to release resource allocated for the log group, and frees it from the internal list in the container.No actions are performed if a log group cannot be located in the method.

Name of the log group removed from the container.
Pointer to the TLazLoggerLogGroup entry to remove from the container.
Constructor for the class instance.

Create is the constructor for the class instance. It allocates the internal TFPList instance used to store TLazLoggerLogGroup entries in the container.

Destructor for the class instance.

Destroy is the overridden destructor for the class instance. It call Clear to remove all log group entries in the container, and frees the internal list where the log group entries are stored. Destroy calls the inherited method prior to exit.

Stores values from the log group list in Src in the current class instance.
Logger group list with values stored in the current class instance.
Gets the ordinal position in the container for the specified log group.
Ordinal position in the container for the specified log group.
Name of the loag group to locate in the container.
Pointer to the log group to locate in the container.
Gets a pointer to the log group with the specified name.
Pointer to the log group located in the method, or Nil when not found.
Name of the log group to locate in the container.
Gets the number of log groups stored in the container.
Number of TLazLoggerLogGroup instances stored in the container.
Provides indexed access to log group entries in the container by their ordinal position.
Ordinal position for the log group retrieved from the container.
Defines the base class for loggers used in the Lazarus IDE.

TLazLogger is a TRefCountedObject descendant which implements the base class for the logger mechanism used in the Lazarus IDE and the LCL. TLazLogger defines the interface used for the various logger classes which write their content to a specific destination. Many of the method which perform the output are empty implementations, and must be re-implemented in descendent classes which write to a file or to the debugger.

Performs actions needed to initialize the logger class instance.

DoInit has an empty implementation. It must be re-implemented in a descendent class to perform the actions needed for the logger type.

Performs actions needed to finalize the logger class instance.
Deprecated. Use DoFinish instead.
Increases the nesting level for the logger.

IncreaseIndent is an overloaded method used to increment the nesting level for output from the logger. The overloaded variant allow the method to be called without parameters, or with a record for an enabled log group. Both variants have an empty implementation, and must be overridden to perform the actions needed for the output destination in the descendent logger.

Identifies the enabled log group for the nesting level.
Decreases the nesting level for the logger.

DecreaseIndent is an overloaded method used to decrement the nesting level for output from the logger. The overloaded variant allow the method to be called without parameters, or with a record for an enabled log group. Both variants have an empty implementation, and must be overridden to perform the actions needed for the output destination in the descendent logger.

Identifies the enabled log group for the nesting level.
Performs actions needed when the nesting level for the logger has been changed.

IndentChanged has an empty implementation, andmust be overridden in a descendent class to perform the actions needed when the nesting level (Increaseindent, DecreaseIndent) has been changed.

Gets the value for the indexed BlockHandler property.
Value for the indexed property.
Ordinal position for the property value retrieved in the method.
Implements the DbgOut method for the logger type.

DoDbgOut has an empty implementation, and must be overridden in a descendent class to perform any actions needed for the output destination for the logger type.

String value written in the method.
Implements the DebugLn method for the logger type.
String value written in the method.
Implements the DebugLnStack method for the logger type.
String value written in the method.
Converts the specified array of values to a string which can be displayed using the output methods for the logger type.

The return value is generated by calling DbgS or DbgSName for the value types in the array elements. For string and character types, the values are converted and cast using AnsiString, WideString, or RTTI routines as needed. An unknown value type is represented in the string using '?unknown variant?'.

String representing the values in the specified array.
Array of constant values converted to a string in the method.
Indicates whether the Init method has already been called for the logger class instance.

Used and updated in the Init method to determine whether DoInit is called. DoInit is not called when IsInitialized is set to True.

Constructor for the class instance.

Create is the constructor for the class instance. It calls the inherited method on entry, and allocates or initializes members in the class instance.It calls InitCriticalSection to allow the thread manager to set up the critical section used to protect resources in the class instance.

Destructor for the class instance.

Destroy is the overridden destructor for the class instance. It calls the Finish method to finalize the logger class instance, and releases and nils the reference-counted LogGroupList property. It calls the inherited destructor prior to signalling the DonCriticalSection handler for the critical section used in the class instance.

Copies values from the logger instance in Src into the current class instance.

No actions are performed in the method when Src has not been assigned.

Copies values from the NestLvlIndent, MaxNestPrefixLen, and UseGlobalLogGroupList properties in Src into the current class instance. Values from LogGroupList in Src are also assigned to the current class instance.

Logger instance with values copied in the method.
Initializes the logger class instance.

Ensures that the EnterCriticalSection handler in the thread manager is signalled for the critical section used to protect resources in the class instance. Calls the DoInit method, and sets IsInitialized to True.

FInalizes the logger class instance.
Gets the current indentation level for the logger.

Always returns 0. Must be overridden in a descendent class to return a value appropriate for the logger type.

Always returns 0.
Indicates the current nesting level for call to the logger class instance.
Indicates the maximum length for the nexting prefix used when values are output in the logger.
Creates a log group and optionally sets its enabled status.
Retrieves or creates a log group for the logger.
Container with the group instances for the logger.
Indicates if the gloabal DebugLoggerGroupList is used as the value for the LogGroupList property.
Adds the specified handler for blobk Enter and Exit conditions.
Removes the specified block hander for the logger type.
Gets the number of block handlers added to the logger type.
Number of block handlers for the logger type.
Provides indexed access to the Block handlers for the logger type.
Ordinal position for a block handler in the logger class instance.
Calls DoDebuglnStack to write the message in s when the logger has been enabed.
Message written in the method.
Generates a log message with formatted value(s) for the specified type(s).
String value for the message.
Array of constant value(s) for the message.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
Writes a message to the logger class instance at the current indentation level.

DebugLn is used to write a log message using the logger class instance. DebugLn is overloaded in TLazLogger to provide variants which accept String or Array values, a Format()-like expression, or a fixed number of String arguments.

DebugLn calls the DoDebugLn method to write the formatted string with the message for the logger class instance.

String argument for the method.
Array of constant values written in the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
Increases the indentation level for the logger and writes an optional log message.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
Decreases the indentation level for the logger and writes an optional log message.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
String argument for the method.
Writes addresses and exception frames representing the backtrace for an exception.
Defines a logger which allows enabling / disabling groups from the command line.

TLazLoggerWithGroupParam allows enabling / disabling groups from the command line. TLazLogger provides only storage for LogGroups, it does not need to enable/disable them, as it discards all logging anyway.

???
Writes a message to the log.

Calls the DebuglnStack method for the logger class instance.

Writes a message to the log.

Writes the text to the log. Does not append a new line. The Argument can be:

- One or more string(s)
- An open array of const: All values are converted to string and joined
- A single string and open array of const: Will be passed to Format
- Any of the above with a PLazLoggerLogGroup as filter

This is a forwarder to the log TLazLogger object. See there for details.

GetDebugLogger SetDebugLogger
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
Writes a message to the log.

Writes the text to the log. Does append a new line.

The Argument can be:

- One or more string
- An open array of const: All values are converted to string and joined
- A single string and open array of const: Will be passed to Format
- Any of the above with a PLazLoggerLogGroup as filter

This is a forwarder to the log TLazLogger object. See there for details.

GetDebugLogger SetDebugLogger
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
Writes a message to the log.

Writes the text to the log. Does append a new line. Increases the current intend.

The Argument can be:

- One or more string
- An open array of const: All values are converted to string and joined
- A single string and open array of const: Will be passed to Format
- Any of the above with a PLazLoggerLogGroup as filter

This is a forwarder to the log TLazLogger object. See there for details.

GetDebugLogger SetDebugLogger
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
Writes a message to the log.

Writes the text to the log. Does append a new line. Increases the current indentation level.

The Argument can be:

- One or more string
- An open array of const: All values are converted to string and joined
- A single string and open array of const: Will be passed to Format
- Any of the above with a PLazLoggerLogGroup as filter
- This is a forwarder to the log TLazLogger object. See there for details.

GetDebugLogger SetDebugLogger
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
String argument for the routine.
Generates a debugger message formatted with the value(s) for the specified type(s).
String with the formatted content for the specified value(s).
Cardinal value for the message.
Integer (LongInt, Int64) value for the message.
QWord value for the message.
TRect value for the message.
Untyped pointer value for the message.
Extended value for the message.
Number of decimal places for the Extended value in the message.
Boolean value for the message.
TMethod value for the message.
String value for the message.
Integer value for the message.
Integer value for the message.
Integer value for the message.
Integer value for the message.
TShiftStateEnum value for the message.
Generates a debugger message with the combined values of the specified arguments.
Message with the values in s1 and s2 combined into a single string.
String value for the message.
String value for the message.
Generates a message with the optional name and class type for the specified object.

DbgSName generates a log message with the optional name and class type for the object in p.

When p has not been assigned, the return value contains:

'Nil'

When p is a TComponent descendant, the return value contains a value like:

TComponent.Name + ':' + TComponent.ClassName

Otherwise, the return value is set to:

TObject.ClassName

If the LazLogger_Dummy unit has been included in the application, the return value is an empty string.

Formatted message with the optional name and class type for the specified value.
TObject instance examined in the routine.
Generates a message with the hexadecimal-encoded memory content for the specified object instance.
String with hexadecimal-encoded values for the specified object instance.
Object instance examined in the routine.
Generates a message with the hexadecimal representation for the specified Int64 value.
String with the hexadecimal representation for the specified value.
Int64 value converted in the routine.
Generates a message with the tick count for the computer system.
String with the tick count for the system.
Generates a message with the hexadecimal-encoded content for the specified block of memory and size.
Untyped pointer to the byte values examined in the routine.
Number of bytes from the pointer to include in the message.
Maximum number of columns to use in the formatted message string. A LineEnd sequence is inserted in the message when Width is exceeded.
Generates a message with the hexadecimal-encoded values from the specified memory stream.
Write the stack trace back when an exception is detected.

Calls the DumpExceptionBackTrace method for the logger in the DebugLogger variable.

Implements the Assign (':=') operator using a Pointer to a logger group for the TLazLoggerLogEnabled type.
Implements the Assign (':=') operator using a Boolean argument for the TLazLoggerLogEnabled type.
Implements the logical And operator for TLazLoggerLogEnabled types.
Implements the logical Or operator for TLazLoggerLogEnabled types.
Gets the ordinal position for the specified parameter name in the command line for the application.
Position for the named parameters.
Parameter name to locate in the command line arguments.
The the value for the specified parameter name from the command line for the application.
Value for the named parameter, or an empty string when not found.
Name of the parameter to locate in the command line arguments.
Gets the value for the DebugLoggerGroups property.
Sets the value for the DebugLoggerGroups property.
New value for the DebugLoggerGroups property.
Gets the value for the DebugLogger property.
Value for the DebugLogger property.
Gets an existing instance of the logger class type without forcing it to be created.
Sets the value for the DebugLogger property.
New value for the DebugLogger property.
Discards an re-creates the logger class instance got the logger type.
Unit property with the logger class instance for the logger type.
Unit property with the list of log groups defined for a logger class instance.
Generates a debugger message with the content from the specified value.
Generates a debugger message with the specified WideString content.
Convenience routine used to write a debugger message with the current content of the stack.
Function type used to create a TLazLogger instance for use with the Lazarus debugger.

The return value is a TRefCountedObject object instance, and can be smart-linked away if none of the routines are used in the application.

Reference-counted object for the TLazLogger instance.
Address of the routine used to create a TLazLogger instance for use with the Lazarus debugger.
Address of the routine called to perform DebugLn output for the logger type.
Address of the routine called to perform DbgOut output for the logger type.