EurekaLog's blog

Logging additional exception information

2026-04-11T21:38:00.014+01:00

This article discusses logging of exception's additional properties into EurekaLog bug reports.

What this article is about

EurekaLog exception tracer creates bug reports for each unhandled exception in your app. For example (a part of bug report is shown):

Exception:
-------------------------------------------------------------------------------------------------------------------------------
  2.1 Date          : Sat, 11 Apr 2026 15:51:09 +0300
  2.2 Address       : 012AB618
  2.3 Module Name   : Project1.exe
  2.4 Module Version: 1.0.0.0
  2.5 Type          : EAccessViolation
  2.6 Message       : Access violation at address 012AB618 in module 'Project1.exe' (offset A9B618). Write of address 00000000.
  2.7 ID            : 73BA1063

EurekaLog captures type (class) of the exception object and its message. However, some exception classes may have additional information. For example:

type
  EOleException = class(EOleSysError)
  private
    FSource: string;
    FHelpFile: string;
  public
    constructor Create(const Message: string; ErrorCode: HRESULT;
      const Source, HelpFile: string; HelpContext: Integer);
    property HelpFile: string read FHelpFile write FHelpFile;
    property Source: string read FSource write FSource;
  end;

The EOleException class has additional HelpFile and Source properties, and its ancestor (the EOleSysError class) also has an additional ErrorCode property.

Historically, EurekaLog only saves the exception class and its message to bug reports. This is because EurekaLog doesn't know about other exception classes, as other exception classes are defined in units other than System.SysUtils. For example, the EOleException class is defined in the System.Win.ComObj unit. Referencing this unit directly (so EurekaLog could reference the EOleException class) would mean that every application running EurekaLog would carry COM code.

The same is true for other classes: EUpdateError (defined in the Data.DB unit), EZipFileNotFoundException (defined in the System.Zip unit), ESocketError (defined in the System.Net.Socket unit), EJSONException (defined in the System.JSON unit), DOMException (defined in the Xml.xmldom unit), EXMLException (defined in the Xml.Internal.OmniXML unit), ERemotableException (defined in the Soap.InvokeRegistry unit), ERequestError (defined in the REST.Types unit), and so on - you get the idea: you definitely don't want to include all these units in your practically empty application if you're just adding EurekaLog to it.

Previosly, if you wanted to have additional properties of exceptions listed in your bug reports - you have to log it manually. However, there is another way starting with EurekaLog 7.15.

Logging additional exception properties

EurekaLog 7.15 has the \Source\Extras\EExtraExceptionInfo.pas unit, which is added to each project with EurekaLog by default. Once the EExtraExceptionInfo unit is added to your project - it will register a callback which will save additional properties of known exception classes into bug reports produced by EurekaLog:

Exception:
-----------------------------------------------------
  2.1 Date          : Sat, 11 Apr 2026 20:35:48 +0300
  2.2 Address       : 0137F5D9
  2.3 Module Name   : Project1.exe
  2.4 Module Version: 1.0.0.0
  2.5 Type          : EOleException
  2.6 Message       : Catastrophic failure.
  2.7 ID            : 2EBFEC43

Custom Information:
---------------------------------------
  9.1 EOleSysError.ErrorCode: $8000FFFF

Customization

There is a catch though. The EExtraExceptionInfo unit knows only about exceptions from the System.SysUtils unit by default. If your project uses other units (such as System.Win.ComObj for the EOleSysError exception class from the example above) - these has to be enabled explicitly. The way to do this is to use conditional defines:

Open your project in IDE;
Go to IDE's "Project" / "View source". This will open your project (.dpr) file in IDE's editor;
You should see the list of EurekaLog units being included into your project. Find the EExtraExceptionInfo unit, place cursor on it;
Press Ctrl + Enter, or right click with the mouse and select the "Open File At Cursor" command.

This will open the EExtraExceptionInfo.pas file in IDE's editor.

The beginning of the EExtraExceptionInfo.pas file has a detailed description of all exception classes which it supports:

...
//
// Select/add option(s) for exception classes which are used in your app:
//

// [System.Win.ComObj] EOleSysError, EOleException
// {$DEFINE E_SYSTEM_WIN_COM_INFO}

// DEPRECATED [Vcl.OleAuto] EOleSysError, EOleException (Delphi 6+)
// {$DEFINE E_VCL_OLEAUTO_INFO}

// [Data.DB] EUpdateError
// {$DEFINE E_DATA_DB_INFO}

// [System.Zip] EZipFileNotFoundException
// {$DEFINE E_SYSTEM_ZIP_INFO}
...

You can browse this list and find units which are being used in your project. For example, if your project references the System.Win.ComObj unit - you would need the E_SYSTEM_WIN_COM_INFO symbol. If your project references the Data.DB unit - you would need the E_DATA_DB_INFO symbol. And so on.

Tip: if you don't know what units are being used in your project - use the "Start" / "Programs" / "EurekaLog" / "Tools" / "PE Analyzer" tool to look what is inside your compiled executable file.

Once you have learned the names of all the symbols you need - go to project's options (use IDE's "Project" / "Options" menu item). Then open conditional defines settings. These can be located in various places - depending on your IDE and personality. For example, it is located on the "Building" / "Delphi compiler" tab for modern Delphi:

Click on the image to enlarge

Add all symbol names which you learned on the previous step. We recommend to add symbol names either to the "All configuration" target or to the platform-specific target. Adding a symbol name will uncomment code in the EExtraExceptionInfo unit, which will include the corresponding unit and extract additional info. Like so:

uses
  {$IFDEF E_SYSTEM_WIN_COM_INFO}ComObj,{$ENDIF}
  
...

  {$IFDEF E_SYSTEM_WIN_COM_INFO}
  if E is ComObj.EOleSysError then
  begin
    Fields.Values['EOleSysError.ErrorCode']   := '$' + IntToHex(ComObj.EOleSysError(E).ErrorCode, 8);
    if E is ComObj.EOleException then
    begin
      Fields.Values['EOleException.Source']   := ComObj.EOleException(E).Source;
      Fields.Values['EOleException.HelpFile'] := ComObj.EOleException(E).HelpFile;
    end;
  end;
  {$ENDIF}

That is why the EExtraExceptionInfo unit is placed as source code (.pas) file into the \Source\Extras\ folder: so it can be recompiled from the source code when conditional defines change - unlike regular EurekaLog units which come precompiled and never change.

IMPORTANT NOTE: do not forget to make a full build of your project (not just compile) after changing the conditional defines option.

Using EExtraExceptionInfo with your own callbacks

The EExtraExceptionInfo unit adds exception information into the "Custom information" section of your bug reports. However, you may also add your own custom information. For example:

procedure AddMyData(const ACustom: Pointer;
  AExceptionInfo: TEurekaExceptionInfo; ALogBuilder: TBaseLogBuilder;
  ADataFields: TStrings; var ACallNextHandler: Boolean);
begin
  // Your own code here. Code below is just an arbitrary example
  ADataFields.Values['License'] := GetUserLicense;
  ADataFields.Values['User']    := GetUserName;
  ADataFields.Values['Build']   := '3.5';
end;

initialization
  RegisterEventCustomDataRequest(nil, AddMyData);
end.

How will your own event handler play with EurekaLog's EExtraExceptionInfo unit?

RegisterEvent* functions add event handlers into lists. EurekaLog would call each registered handler from a list until there are no more handlers or some handler would return ACallNextHandler = False. So, if you register your own OnCustomData event handler - it will be called together with the EExtraExceptionInfo unit, producing the following output (see code examples above):

Exception:
-----------------------------------------------------
  2.1 Date          : Sat, 11 Apr 2026 20:35:48 +0300
  2.2 Address       : 0137F5D9
  2.3 Module Name   : Project1.exe
  2.4 Module Version: 1.0.0.0
  2.5 Type          : EOleException
  2.6 Message       : Catastrophic failure.
  2.7 ID            : 2EBFEC43

Custom Information:
-------------------------------------------------
  9.1 EOleSysError.ErrorCode: $8000FFFF
  9.2 License               : kjlasdioj234879asd
  9.3 User                  : example@example.com
  9.4 Build                 : 3.5

Here: the 9.1 line is produced by the EExtraExceptionInfo unit, while 9.2-9.4 lines are produced by your code (event handler).

The last argument for any RegisterEvent* function (named AFirst) defines if the function should add your handler to the beginning of the list (AFirst = True) or to the end (AFirst = False; default). For example, registering your handler like so:

initialization
  RegisterEventCustomDataRequest(nil, AddMyData, True { - added });
end.

will produce the following output:

Exception:
-----------------------------------------------------
  2.1 Date          : Sat, 11 Apr 2026 20:35:48 +0300
  2.2 Address       : 0137F5D9
  2.3 Module Name   : Project1.exe
  2.4 Module Version: 1.0.0.0
  2.5 Type          : EOleException
  2.6 Message       : Catastrophic failure.
  2.7 ID            : 2EBFEC43

Custom Information:
-------------------------------------------------
  9.1 License               : kJlaSdioj23t879aSd
  9.2 User                  : example@example.com
  9.3 Build                 : 3.5
  9.4 EOleSysError.ErrorCode: $8000FFFF

As you can see, now it is your output listed first, followed by the output from the EExtraExceptionInfo unit.

And since your handler will be called first (before EExtraExceptionInfo unit) - you can also do something like this:

procedure AddMyData(const ACustom: Pointer;
  AExceptionInfo: TEurekaExceptionInfo; ALogBuilder: TBaseLogBuilder;
  ADataFields: TStrings; var ACallNextHandler: Boolean);
begin
  ADataFields.Values['License'] := GetUserLicense;
  ADataFields.Values['User']    := GetUserName;
  ADataFields.Values['Build']   := '3.5';
  
  // Do not call code from EExtraExceptionInfo for the EOleException exceptions 
  if AExceptionInfo.ExceptionClass = EOleException.ClassName then
    ACallNextHandler := False;
end;

Additionally, if you don't want to add additional exception properties to the custom information section - you can change this behaviour to adding additional exception properties to exception's message. You need to add the E_ADD_CUSTOM_MESSAGE symbol to conditional defines. Doing so will produce the following output:

Exception:
-----------------------------------------------------
  2.1 Date          : Sat, 11 Apr 2026 20:35:48 +0300
  2.2 Address       : 0137F5D9
  2.3 Module Name   : Project1.exe
  2.4 Module Version: 1.0.0.0
  2.5 Type          : EOleException
  2.6 Message       : Catastrophic failure.
                      ErrorCode=$8000FFFF
  2.7 ID            : 2EBFEC43

Custom Information:
----------------------------------
  9.1 License: kJlaSdioj23t879aSd
  9.2 User   : example@example.com
  9.3 Build  : 3.5

Here: the "ErrorCode" line is added to exception's message by the EExtraExceptionInfo unit with the E_ADD_CUSTOM_MESSAGE option, while "Custom Information" section is composed by your AddMyData OnCustomData event handler from the example above.

You may also enable the E_ADD_NO_CUSTOM_INFO option (by adding its symbol's name to conditional defines) to completely disable assist from the EExtraExceptionInfo unit.

Implemenation details

The EExtraExceptionInfo unit is distributed as a source code (.pas) file located in the \Source\Extras\ folder of your EurekaLog installation - as opposed to the usual EurekaLog units, which are distributed as precompiled (.dcu/.obj) files located in the \Lib\ folder of your EurekaLog installation. It is shipped as source code even in those editions of EurekaLog that are normally distributed without source code (Trial and Professional). That is because you can't use the same precompiled EExtraExceptionInfo unit in all projects, you need to actually change this unit (by commenting/uncommenting parts of its code - which is done by defining conditional symbols) adapting to each application.

EurekaLog is installed into the Program Files folder by default - which is write-protected for normal users. So adding source code files to your project from such location can lead to compilation failures when the compiler won't be able to write *.dcu and *.hpp files into that location (it is true for older IDEs, which has a default compiled units output folder match the source code location). That is why the \Source\Extras\ folder is marked as writeable.

P.S. The \Source\Extras\ folder was not writable in EurekaLog earlier than 7.16 (e.g. 7.15.*, etc.). There was an alternative workaround: files from the \Source\Extras\ folder were cloned (copied) into your project's folder. This copy behaviour still exists in EurekaLog 7.16+, but it is disabled by default. If you want to enable this copy behaviour back for whatever reason: open EurekaLog settings for your project (go to "Project" / "EurekaLog options" in IDE's menu), then switch to the "Advanced" / "Custom/Manual" tab. Find the "ExtrasCopy" line (if it is present) and change it to 1. If the line does not exist (which is the default) - add it to any location:
ExtrasCopy=1
(default is 0 on EurekaLog 7.16, while it is 1 on earlier versions)
You can also open the .eof file for your project in any text editor and edit property manually.

And while we are on this topic - you can also add:
ExtrasAdd=0
(default is 1)
to completely disable adding the EExtraExceptionInfo unit to your project.

EurekaLog 7.15 is out

2026-03-31T11:37:00.000+01:00

We are pleased to announce the availability of the new 7.15 version.

EurekaLog is a tool for Delphi and C++Builder that gives your application the power to catch every exception and memory/resource leak, generating a detailed log of the call stack (with unit, procedure and line number), optionally sending you a copy of each log entry via email or the Web via the most used Web Bug-Tracking tools (as Mantis, BugZilla, FogBugz, JIRA, YouTrack, Redmine, Exceptionless, GitLab, and GitHub).

EurekaLog represents the most advanced exception and memory leaks logger technology available for Delphi/C++Builder developers.

To learn more about EurekaLog, please visit our website at:
https://www.eurekalog.com

To download a demo, please visit:
https://www.eurekalog.com/downloads

If you would like to purchase a new license, please visit:
https://www.eurekalog.com/buy

Changes in 7.15 build:

Added: Recompiled for RAD Studio 13 update 1
Added: \Source\Extras\EExtraExceptionInfo.pas for extracting additional fields of exception objects
Added: The new _LOCATION_ function (combination of unit, class, function, line number)
Added: The CurrentAddress function (ECallStack unit) - to avoid inclusion of ELowLevel for the GetEIP function
Added: Added the ResStringCleanupCache function (EResourceStrings unit)
Added: Registers preview on the Assembler tab
Added: Stack dump improvements: EBP is highlighted, stack dump size is increased to include all arguments
Added: New localized languages
Added: Support for JSON and XML for HTTP posting
Added: Expanding environment variables for passwords
Added: The new TThreadData.OnExit event - free to use for any purposes
Added: Preparation for BugID as arbitral string - currently for internal use only
Added: IDE's "Tools" / "EurekaLog" / "Bug Reports" / "Delete old bug reports..." menu item
Added: EurekaLog news/updates/RSS notifications in IDE
Fixed: Major rewrite of lightweight DLLs
Fixed: Using deprecated API in Jira
Fixed: Stripping headers from web-fields
Fixed: Wine compatibility for DLLs with packages
Fixed: Possible unexpected resetting of last error in DLLs
Fixed: Rare deadlock when opening a locked bug report file
Fixed: Very rare deadlock in multithreading apps
Fixed: A minor performance optimization for call stack tracing
Fixed: Improvements for __initialize_security_cookie/__security_cookie_check functions (functions now also check return addresses; an additional human-readable description can be passed to __security_cookie_check)
Fixed: Very rare memory corruption bug on shutdown during leaks checks
Fixed: Various improvements on startup and shutdown stage
Fixed: Various improvements for handling stack overflows
Fixed: Updated existed localized languages
Fixed: Other minor improvements
Changed: Updated the included VirtualMM

See full change log here.

EurekaLog 25% Christmas Sale + 3 Months Extra of Maintenance Period

2025-12-19T21:26:00.001+00:00

We're excited to announce a special EurekaLog Christmas sale!

During this magical holiday season, we want to thank our users for their trust and give them a special surprise. EurekaLog continues to help developers around the world — and we're celebrating these successes with you.

Use the XMAS2025 discount coupon when purchasing a new license or a prolongation to get a 25% discount and a bonus of 3 extra months of maintenance period. The offer is valid starting December 23 and ends at the end of December 31.

You can use the discount code here:

https://www.eurekalog.com/buy.php

Please, do not forget to log in into your account, if you already own a EurekaLog license.

Black Friday and Cyber Monday Sale

2025-11-25T11:00:00.001+00:00

We are pleased to announce Black Friday and Cyber Monday 30% discount on any of our EurekaLog products using the coupon code found below.

The sale starts on Black Friday (November, 28) and ends at the end of Cyber Monday (December, 1).

Enter this code when paying for the item on our web site:

BFCM2025

Existing customers with valid or expired licenses can log in and purchase upgrades, new licenses and extensions here:

https://www.eurekalog.com/login.php

Use the login credentials we sent you at purchase time.

New customers (without existing licenses) can use the discount code here:

https://www.eurekalog.com/buy.php

Managing local bug reports by bug reports file rotation

2025-11-08T13:34:00.002+00:00

EurekaLog can store bug reports locally - in a text file. This file is used both as a log and as a database. Each exception will be appended to the local bug report file. Some users want to know how to set up bug report file rotation. Log rotation is the automated process of managing log files to prevent them from growing too large, which can impact system performance and storage. It involves doing something with old log files (compressing, archiving, renaming, or deleting) and creating a new, empty one to continue recording new events.

This article will discuss what options you have for EurekaLog's local bug reports file.

Why you may want a bug reports file rotation

First of all - EurekaLog is a tool which is designed to collect bug reports from PCs of your users/clients. It means its primary purpose is to send bug reports to you via some sending method - be it a simple e-mail or a dedicated bug tracker. Therefore, local bug reports file is completely useless to you (the developer), as you typically don't have any remote access to PCs of your users/clients. In other words, local bug reports file rotation is not a problem for like 90% of EurekaLog's users, because you will be receiving bug reports and not using the local bug reports file in the first place.

Therefore, if you set up sending in EurekaLog, you will probably want to disable storing local bug reports completely. Thus, avoiding the rotation problem altogether.

However, there are cases when you do need to use local bug reports:

Some of EurekaLog's users use it in a way it was not designed to perform (at least it was not EurekaLog's main purpose). Specifically, they use EurekaLog as a replacement for IDE's debugger - to perform a local debugging/troubleshooting on their development machines. Naturally, they will use the local bug reports file and not set up any sending;
Some of EurekaLog's users develop apps which are designed to be run in private corporate environments. Corporate environments may have strict rules on network connectivity, so setting up sending is not viable/possible. Naturally, they will also use the local bug reports file and not set up any sending. For example, an app may be configured to store bug reports on a shared network drive, which can be accessed by you (the app's developer).

Once local bug reports file is enabled/set up - there may be two completely different reasons why you may want to implement a bug report file rotation:

Removing obsolete bug reports. For example, you probably are not interested in bug reports from 5-10 years ago, as these will likely be irrelevant. That is - assuming you release updates to your app regularly.
Managing size of bug report files. This matters most for apps which run 24/7 non-stop, such as services. If your service is configured to continue to run after crashing with exception - your local bug reports file may grow fast.
This reason is probably irrelevant for non-service apps, because you will likely to wipe obsolete bug reports (as in #1 above) long before file size become a problem.

Note:

If you need to implement any custom way to deliver reports to yourself (be it saving into a specific folder, inserting into database, or something else) - it is better to implement this as "sending", rather than "saving" (for example, saving/inserting bug report in the OnExceptionNotify event handler). That way you will actually be sending reports, so you can disable the local bug reports file - thus having all sending rules applied and without worrying about local bug reports file rotation in the first place.

Bug reports are not log entries

EurekaLog does not have any sort of automated process, which is typically scheduled to run at regular intervals (e.g., hourly, daily, weekly) or when a file reaches a certain size. That is because local bug reports file contains bug reports - a valuable information. It is not a log - which contains auxilary (less important) info. That is why EurekaLog will never delete bug report files without your explicit command. It is up to you to decide which bug reports are important and which ones are no longer relevant.

Managing size of bug report files

This is the most simple and straightforward way: you don't care about importance of bug reports, you just want to avoid unlimited file size grow. Perhaps, you are using local bug reports file as a backup to sending, so you are not really worried about losing precious reports.

If this is the case - there are the "Max. reports in one file" and "Do not save duplicate errors" options. You can limit how much bug reports can a single local bug reports file hold by altering these options. While you can't specify a file size limit in bytes, but you do this by specifying file size limit in reports. That way you will use a single local bug reports file, and will limit its size to some reasonable value of your choice.

There is also the "Delete file at startup" option, which can be useful in some cases.

Removing obsolete bug reports

If you don't care about limiting file size, but rather want to tidy up your reports - you may want to delete old reports which lost their importance.

EurekaLog has the "Delete file at version change" option, which will create a fresh local bug reports file once you deploy a new version of your application. This option requires you to embed version information into your executable, as well as increase it for each build/release. This option works well if you release new builds/versions of your app more or less regularly, and your users/clients/customers upgrade your app. This option will be useless if you very rarely make new releases, or if your users/clients/customers prefer to stay at single version of your app.

There is also IDE's "Tools" / "EurekaLog" / "Bug reports" / "Delete old bug reports..." menu item, which you can invoke manually as often as you like:

Bug reports cleanup from IDE

There is no other option which can delete local bug reports file due to it obsolesence. However, what you can do is to have multiple local bug reports files. For example, if you are developing a service application, you may want to use a new local bug report file for each day, week or month. Other possible alternative is to have one file per each bug (so the single file will contain multiple reports of the same bug). You can do either of these by using either variables or events:

Using variables to rotate the local bug report file

The default output for local bug report file is
%AppData%\Neos Eureka S.r.l\EurekaLog\Bug Reports\%_ThisModuleName%\
which will be expanded to something like
C:\Users\your_user_name\AppData\Roaming\Neos Eureka S.r.l\EurekaLog\Bug Reports\Project1.exe\Project1.el
at run-time. Notice how it will be the same file name for each bug/exception.

You can alter local bug report file name to something like
%AppData%\Neos Eureka S.r.l\EurekaLog\Bug Reports\%_ThisModuleName%\%_ThisModuleName%_%DateFmt%.el
which will be expanded to
C:\Users\your_user_name\AppData\Roaming\Neos Eureka S.r.l\EurekaLog\Bug Reports\Project1.exe\Project1.exe_20251031.el
at run-time. The important part: the expansion of environment variables happens during exception's processing. In other words, the local bug report file name will be calculated for each exception, resulting in multiple local bug report files if your application will run for multiple days.

Obviosly, if you want your bug report file to contain multiple bug reports at once - you need to increase the above mentioned "Max. reports in one file" limit, because the default value is 1 (a bug report file can store only one bug report).

Notice how you can change both folder name only (when ending with trailing path delimiter) or file name (when ending with file extension), so you can have one file per day or one folder per day.

You can also use something like
%AppData%\Neos Eureka S.r.l\EurekaLog\Bug Reports\%_ThisModuleName%\%_ThisModuleName%_%_BugID%.el
which will be expanded to
C:\Users\your_user_name\AppData\Roaming\Neos Eureka S.r.l\EurekaLog\Bug Reports\Project1.exe\Project1.exe_00CAB105.el
at run-time. That way you will have a standalone local bug report file for each bug/exception.

Or you can even combine the two together like so:
%AppData%\Neos Eureka S.r.l\EurekaLog\Bug Reports\%_ThisModuleName%\%DateFmt%\%_ThisModuleName%_%_BugID%.el
resulting in file names like

C:\Users\your_user_name\AppData\Roaming\Neos Eureka S.r.l\EurekaLog\Bug Reports\Project1.exe\20251031\Project1.exe_00CAB105.el

Using events to rotate local bug report file

There may be cases when you want to have a logic, which can't be implemented with environment variables. For example, if you want a new local bug report file for each month, but there is no environment variable that defines "a month of bug's occurence". In this case: you can use event handlers.

There is the OnCustomFileName event handler. You may assign your custom code to perform modification of the local bug report file name. You will be insterested in the AFileType = ftSavedBugReport case:

uses
  DateUtils,      // for YearOf and MonthOf
  EEvents,        // for RegisterEventCustomFileName
  EException,     // for TEurekaExceptionInfo
  EConsts,        // for EEurekaLogReportExt
  ETypes,         // for TEurekaLogFileType
  ECompatibility; // for YearOf and MonthOf on IDEs which do not have the DateUtils unit

// Alter local bug reports file name in any way we want
procedure ChangeLocalBugReportFileName(const ACustom: Pointer; 
  AExceptionInfo: TEurekaExceptionInfo; 
  const AFileType: TEurekaLogFileType; 
  var AFileName: String; 
  var ACallNextHandler: Boolean);
begin
  // Is this a local bug reports file name?
  if AFileType = ftSavedBugReport then
    // If yes - then change it
    // This code is just an example
    // Replace it with your own code
    AFileName := ExtractFilePath(AFileName) + // folder
                 Format('%s_%d_%d%s',         // file
                   [ExtractFileName(AExceptionInfo.ExceptionModuleName),
                    YearOf(AExceptionInfo.Time),
                    MonthOf(AExceptionInfo.Time),
                    EEurekaLogReportExt]);
end;

initialization
  // Ask EurekaLog to use our code to customize local bug reports file name
  RegisterEventCustomFileName(nil, ChangeLocalBugReportFileName);
end.

This code will produce file names like
C:\Users\your_user_name\AppData\Roaming\Neos Eureka S.r.l\EurekaLog\Bug Reports\Project1.exe\Project1.exe_2025_10.el

Naturally, you can do literally anything with the local bug reports file name when you are using an event handler.

Obviosly, if you want your bug report file to contain multiple bug reports at once - you need to increase the above mentioned "Max. reports in one file" limit, because the default value is 1 (a bug report file can store only one bug report).

Performing the actual rotation

While both methods discussed above will spawn a new local bug reports files from time to time (based on the conditions that you set) - they will not delete any old files. That is because EurekaLog does not know if you are interested in, say, bug reports from yesterday or not. It is up to you to decide which bug report files are qualified for deletion.

If you are running a normal application (not a service) - then you can perform the check on startup. If you are running a service application - then you may be interesting in performing the check, say, once per 100 exceptions:

uses
  EEvents,    // for RegisterEventExceptionNotify
  EException, // for TEurekaExceptionInfo
  ESysInfo;   // for ExpandEnvVars

// Remove old local bug reports files
procedure LocalBugReportsFilesCleanup; overload;
var
  Folder: String;
begin
  // Change the target folder for your specific location
  Folder := ExpandEnvVars('%APPDATA%\Neos Eureka S.r.l\EurekaLog\Bug Reports\');

  // Write here your code to cleanup old local bug reports files
  // ...
end;

var
  // Counter on how many unhandled exceptions were processed
  // In other words, how many bug reports were created
  GProcessedExceptionsCount: Integer;

// Will be called by EurekaLog for each unhandled exception
procedure LocalBugReportsFilesCleanup(const ACustom: Pointer;
  AExceptionInfo: TEurekaExceptionInfo;
  var AHandle: Boolean;
  var ACallNextHandler: Boolean); overload;
const
  // Customize this constant to your liking
  MaxExceptionsBetweenCleanups = 100;
begin
  // If there were enough exceptions...
  if GProcessedExceptionsCount > MaxExceptionsBetweenCleanups then
  begin
    GProcessedExceptionsCount := 0;
    // ...perform the cleanup
    LocalBugReportsFilesCleanup;
  end;
  Inc(GProcessedExceptionsCount);
end;

initialization
  // Perform the cleanup on startup:
  LocalBugReportsFilesCleanup;
  // Ask EurekaLog to perform the cleanup on exceptions:
  RegisterEventExceptionNotify(nil, LocalBugReportsFilesCleanup);
end.

How to implement the cleanup is up to you and it highly depends on how you organize your reports. For example, if you spawn a new local bug report file each day, you may enumerate all files and delete ones from yesterday or ones older than 1 year. You can extract the date part from a file name (if it is present) to get a sense on when this file was created. Surely, you can also use file's creation or modification date - assuming you are sure file dates were not tampered with.

If you spawn a new local bug report file for each bug/exception, you may collect/group these files into folders corresponding to dates, so you can wipe individual folders (older than X days) instead of files.

Here is an example of how your cleanup code might look like:

uses
  EEvents,        // for RegisterEventExceptionNotify
  EException,     // for TEurekaExceptionInfo
  ESysInfo,       // for ExpandEnvVars
  EConsts,        // for EEurekaLogReportExt
  ETools,         // for BuildFileList and GetFileCreation
  ETypes;         // for amSuperSetOf

// Remove old local bug reports files
procedure LocalBugReportsFilesCleanup; overload;
var
  Folder: String;
  FileName: String;
  Files: TStrings;
  Today: TDateTime;
  FileCreated: TDateTime;
  X: Integer;
const
  MaxAgeInDays = 365;
begin
  // Change the target folder for your specific location
  Folder := ExpandEnvVars('%AppData%\Neos Eureka S.r.l\EurekaLog\Bug Reports\%_ThisModuleName%\');

  // Write here your code to cleanup old local bug reports files
  // The code below is just an example
  // Replace it with your own code

  Today := Now;
  Files := TStringList.Create;
  try
    // Enumerate all local bug report files in the mentioned folder
    AdvBuildFileList(Folder + '*' + EEurekaLogReportExt,
                     faAnyFile, Files, amSuperSetOf,
                     [flFullNames, flRecursive]);
    // Check each found bug report file
    for X := 0 to Files.Count - 1 do
    begin
      // Get file's properties
      FileName := Files[X];
      if not GetFileCreation(FileName, FileCreated) then
        FileCreated := Today;

      // If the file is too old - delete it
      if DaysBetween(Today, FileCreated) > MaxAgeInDays then
        DeleteFile(FileName);
    end;
  finally
    FreeAndNil(Files);
  end;
end;

This code will delete all local bug reports files in the specified folder which are older than 365 days (1 year). If you wish to use a different logic to wipe files (say, wipe files from an older version of your app, wipe files for a fixed bug/exception, or anything else) - you would need to change or adjust this code.

See also:

Introducing VirtualMM debugging memory manager

2025-10-29T10:16:00.009+00:00

We will talk about the VirtualMM debugging memory manager. What it is, when to use it, when not to use it, how to use it, where to download it, how to configure it, and so on.

This article assumes that you are familiar (at least in general terms) with the concepts of address space, memory page, RESERVE, and COMMIT.

Memory architecture in Delphi applications
What is the problem with a memory manager?
How do you find memory bugs in Delphi applications?
What is the VirtualMM debugging memory manager?
Where can I download VirtualMM?
- Where can I download SafeMM?
How do I install VirtualMM?
How do I add (connect) VirtualMM to my project?
How do I configure VirtualMM?
What problems does VirtualMM solve?
When should I use VirtualMM?
When should I NOT use VirtualMM?
Using VirtualMM with EurekaLog
What should I do if my application crashes with "Out Of Memory" when using VirtualMM?
Notes

Memory architecture in Delphi applications

To understand the purpose (essence) of the VirtualMM debugging memory manager, we first need to refresh our knowledge on the basics of memory management (*) in Delphi applications.

How do Delphi applications allocate memory?

To recap: we have a CPU stack for local variables and a block (section) for global variables, as well as dynamic memory (the heap) for any variable-sized data in a Delphi application. Although Delphi has a variety of dynamic data (objects, arrays, strings, interfaces, etc.), they all call the GetMem function in one way or another. For example, creating a string will call the GetMem function, passing it the character size of the string plus the size of the string's service header. Creating an object will call the GetMem function, passing it the object's .InstanceSize property. And so on. In other words, any dynamic data in Delphi is a superset of the GetMem function.

How does System allocate memory?

Just as Delphi has a base memory allocation function (GetMem) that handles all memory allocations, Windows also has its own base memory allocation function: the VirtualAlloc. It actually has several variants, but for simplicity, we'll ignore them. For the purposes of this article, we'll refer to all functions in the "VirtualAlloc family" simply as the "VirtualAlloc function".

What is a memory manager?

If you don't know anything about memory in Delphi and Windows applications, you might assume that the GetMem function in Delphi simply calls the VirtualAlloc function in Windows. In other words, they're the same function. But that's not true: in fact, the GetMem function doesn't call the VirtualAlloc function directly. Instead, the GetMem function calls Delphi's memory manager. Delphi’s memory manager then calls the VirtualAlloc function.

Why do Delphi applications use a memory manager?

Why do we need a memory manager at all? Why can't we use the operating system's memory management functions directly? That is, why can't the GetMem function simply call the VirtualAlloc function? The problem is that the VirtualAlloc function allocates memory at a granularity of 64 KB (**). This means that you can't allocate memory smaller than 64 KB. So, if you allocate 8 bytes for a TObject using the VirtualAlloc function, the VirtualAlloc function will take a full 64 KB from your address space instead of 8 bytes. And these 64 KB cannot be used (to allocate another block of memory via the VirtualAlloc function) until you release the created TObject object and return the allocated memory.

That is, if you create 100 objects of, say, 20 bytes each (very simple objects, you inherited them from TObject), then instead of two kilobytes (20 bytes * 100 = 2 KB), you're now occupying almost 6.5 MB (64 * 100 = 6,400 KB) – several orders of magnitude more!

This is precisely the problem the memory manager solves: it allocates one large chunk of memory using the VirtualAlloc function (for example, 1 MB), and then places several smaller memory allocations into this block, which come from the GetMem function. Thus the memory manager will be able to accommodate approximately 50,000 20-byte objects using a single 1 MB block.

Further in the text, I will refer to allocated/free memory (without quotation marks), meaning actually allocated (free) memory that was allocated and freed through the VirtualAlloc/VirtualFree family of functions.
I will refer to "allocated"/"free" memory (in quotation marks), meaning memory that was allocated (via the VirtualAlloc function), but logically marked as allocated or free through the GetMem/FreeMem functions.

What is the problem with a memory manager?

Let's say you allocated memory for an object using the VirtualAlloc function, worked with the object, and then freed it (using the VirtualFree function). If you now mistakenly try to do something with the (already freed) object, you'll get an Access Violation exception because you're accessing inaccessible memory (memory that wasn't allocated). For example:

var
  P: Pointer;
begin
  P := VirtualAlloc({...}); // allocate memory for P
  P^ := {...};              // do something (work) with P
  VirtualFree(P);           // finished working, free the memory

  // BUG: accessing memory that has already been freed
  P^ := {...};              // this line will ALWAYS throw an Access Violation exception
end;

That's good. Memory bugs are immediately visible. We detect them right where they occur.

Will anything change if we don't use the VirtualAlloc function, but use the memory manager (the GetMem function)? Yes, of course it will:

GetMem(P, {...}); // actually: doesn't allocate memory
FreeMem(P);       // actually: doesn't free memory

After all, memory manager functions don't actually allocate or free memory. Instead, they return a pointer to the middle of some (already allocated) memory block and mark this area as "allocated", then simply mark it as "free" at the end. In other words:

var
  P: Pointer;
begin
  GetMem(P, {...}); // "allocate" memory for P
  P^ := {...};      // do something (work) with P
  FreeMem(P);       // finished working, "free" the memory

  // BUG: accessing already freed memory
  P^ := {...};      // this line executes successfully because this memory is still allocated
end;

Since the memory isn't actually freed (but only logically marked as "free"), we can successfully access it even after the object has been logically freed. This is the problem with using a memory manager: a previously obvious memory bug is now hidden.

How do you find memory bugs in Delphi applications?

There are so-called debugging memory managers for Delphi (***). Unlike a regular memory manager, the purpose of a debugging memory manager is to help you diagnose memory problems. How do they do this?

Write after delete

If we look at the example above, the problem is that the memory block, which is logically "free", changes its contents:

FreeMem(P);  // the memory block is now "free"
P^ := {...}; // the "free" memory block has changed

How can a memory manager detect this? For example, a memory manager may fill a "free" block with some known pattern (for example, the $CC byte). Then, if the memory manager allocates a new block of memory and sees that the "free" memory has changed (it doesn't contain the $CC byte at some location), then there was a write to "freed" memory bug. For example:

var
  P: Pointer;
begin
  GetMem(P, {...});
  P^ := {...};
  FreeMem(P);

  // BUG: accessing already freed memory
  P^ := {...};      // this line executes successfully

  GetMem(B, {...}); // will raise a "memory corruption" error,
  // because the memory manager will see that the memory previously occupied by P has been modified
end;

As you can see, although a memory bug can be detected, it won't be detected at the moment the bug occurred, but much later. This greatly complicates memory diagnostics. This is a problem caused by using a debugging memory manager.

Buffer overflow

Another common bug is writing beyond the bounds of allocated memory. For example:

var
  Buffer: PInteger;
begin
  GetMem(Buffer, Count * SizeOf(Integer)); // "allocate" memory for Count Integers
  for X := 0 to Count do                   // BUG: should be Count - 1
  begin
    Buffer^ := 0;                          // will write data outside the "allocated" buffer on the last step
    Inc(Buffer);
  end;

Here we allocate memory for Count elements, while zeroing out Count + 1 elements (one more than necessary). This means we'll be writing to "free" memory, which is located behind the memory block we've "allocated". The problem is that sometimes this memory isn't "free" but "allocated" by other data. This means we'll corrupt some other memory block located immediately after our memory block. This bug is called a buffer overflow.

How can a debugging memory manager help us with this bug? For example, it might "allocate" more memory than you requested. Let's say you request a 20-byte memory block, and the memory manager "allocates" 28 bytes. It reserves 4 bytes on each side for the template (for example, the $CC bytes). If there's anything different in this reserved area when "freeing" the memory - it means the memory has been overwritten. For example:

var
  Buffer: PInteger;
begin
  GetMem(Buffer, Count * SizeOf(Integer)); // "allocate" memory for Count Integers
  for X := 0 to Count do                   // BUG: should be Count - 1
  begin
    Buffer^ := 0;                          // here: buffer overflow when X = Count
    Inc(Buffer);
  end;
  { ... do something else with Buffer }
  FreeMem(Buffer); // will trigger a buffer overflow error,
  // because the memory manager will see that the memory immediately after our block has been modified.

And again, we see the same problem: the bug will be detected long after it occurs.

Calling methods of a deleted object

Memory isn't just for writing. Memory is often an object. What happens if we try to call a method of an already "freed" object?

Well, a method can be regular (static) or dynamic (virtual).

Calling a static method of a deleted object

A static method is essentially no different from a regular function: it has a fixed address. Therefore, calling a static method doesn't depend on the object's data. Therefore, whether the object is "allocated" or "deallocated" doesn't matter. For example:

var
  L: TList;
begin
  L := TList.Create; // "create" the object
  L.Free;            // "free" the object

  I := L.IndexOf(P); // will execute successfully and return the correct result.

Since the call to the IndexOf method does not use the data of the L object, the memory manager has no influence on the method call. Even if the memory manager frees the object, the method will still be called. Code execution will continue.

Therefore, a debugging memory manager will not be able to detect such a problem.

Note that we are only talking about the call (invokation) of the method. How this method will be executed with an already deleted object is a separate question. We'll look at it later.

Calling a virtual method of a deleted object

The code must read the method's address from the object's data to call a virtual method. If the object is "freed" and its data hasn't changed since it was "freed", then nothing will prevent the virtual method from being called. For example:

var
  S: TStringList;
begin
  S := TStringList.Create; // "create" the object
  // Working with S
  S.Free;              // "deallocate" the object

  I := S.Count;        // will execute successfully and return the correct result

Here, the address of the virtual method GetCount is stored in the S object. When object S is "deleted", the memory it occupied remains accessible, so the method call succeeds.

How can a debugging memory manager catch this problem? Well, for example, it could write a different virtual method address to the memory previously occupied by the S object. And if someone tries to call the object's virtual method after it's "deleted", it will call the debugging memory manager function, which will raise an error:

var
  S: TStringList;
begin
  S := TStringList.Create; // "create" the object
  // Working with S
  S.Free;              // "free" the object

  I := S.Count;        // will raise a "method called on a deleted object" error.

Note: the debugging memory manager was able to catch the error immediately when it occurred in this case - rather than later, as in other examples above.

Read after delete

Memory can be not only written to. You can also read from it. For example:

var
  L: TList;
begin
  L := TList.Create; // "create" the object
  L.Free;            // "free" the object

  I := L.Count;      // will execute successfully and return the correct result.

If the object's memory had been freed (via the VirtualFree function), any attempt to write or read the object's data (fields) would immediately raise an Access Violation exception. But since the object is only "freed" (via the FreeMem function), its data is still accessible, so attempts to read and write (modify) the object's data (fields) will succeed.

How can a debugging memory manager help with this bug? Well, it can't help much. Yes, it can fill the "freed" object with some debugging pattern (the $CC byte, for example), but this won't prevent code from reading and writing the object's data:

var
  L: TList;
begin
  L := TList.Create; // "create" the object
  L.Free;            // "free" the object

  I := L.Count;      // will succeed, but return an incorrect result ($CCCC'CCCC or -858'993'460)

The only chance here is to hope that the data read is so erroneous that it ultimately causes some other exception. This usually happens when the address of something is read from an object.

Therefore, a debugging memory manager may or may not help in detecting this bug.

Memory reuse

Let's look at this example:

var
  S1, S2: TStringList;
begin
  S1 := TStringList.Create; // "create" the object
  // Working with S1
  S1.Free;                  // "free" the object

  S2 := TStringList.Create; // "create" the object

  I := S1.Count;            // logically - a bug, but will always succeed, since S1 = S2

Here we "delete" the object, but immediately "create" an identical one. The addresses of both objects will be the same, i.e. S1 = S2, since the new object will be allocated in the place of the old object. Then we access the first "deleted" object. Technically, S1.Count is the same as S2.Count. Therefore, although this is a logical error in the code, such code will execute without errors, working with S2 instead of S1.

The debugging memory manager cannot detect this problem for obvious reasons.

What is the VirtualMM debugging memory manager?

How can we eliminate the shortcomings of Delphi's debugging memory managers described above? To do this: we need to understand the source of the issues with debugging memory managers. These issues arise from software memory management. It means all memory problems are detected using user code.

Unlike Delphi's memory managers, the system (VirtualAlloc) uses hardware memory management. It means all memory problems are detected by the CPU itself.

Therefore, one way to address the shortcomings of Delphi's debugging memory managers is to switch from software memory management to hardware memory management. This is precisely what the VirtualMM debugging memory manager does: roughly speaking, it replaces the GetMem function with the VirtualAlloc function. Specifically, its name is derived from the words "Virtual" - which refers to the VirtualAlloc function, and "MM" - which stands for Memory Manager.

VirtualMM is a Pascal-based source code. It supports IDEs from Delphi 6 up to the latest available version (RAD Studio 13 Florence at the time of writing). Earlier versions of Delphi (5 and below) are not supported due to compiler's limitations.

It's important to understand that VirtualMM runs noticeably slower (compared to other memory managers with software allocation). This is because user code executes relatively quickly on the CPU. However, switching to kernel mode (which is necessary for hardware memory allocation) is very slow. Therefore, if your program is constantly allocating and freeing memory, be prepared for increased latency.

Recall that the need for memory managers originally arose in Delphi due to the system's 64 KB memory allocation granularity. How does VirtualMM solve this problem?

If your application is 64-bit, then there is almost no problem: the 64-bit address space is 8 TB, which allows you to allocate no more than 134,217,728 memory blocks (ranging from 1 byte to 64 KB in size).
If your application is 32-bit, things are much more complicated: the 32-bit address space is 2 GB (4 GB max), which allows you to allocate only 32,768 memory blocks maximum (ranging from 1 byte to 64 KB in size) – which is terribly small.

That's why the VirtualMM memory manager uses the concept of "small blocks". 64 KB is the memory allocation granularity. In other words, you can't allocate memory starting at an address that isn't a multiple of 64 KB. This means you can allocate memory starting at 65,536 (64k) and 131,072 (128k), but you can't allocate memory starting at any value in between, such as 70,000. However, within these 64 KB, memory can be allocated or deallocated at a granularity of 4 KB (****). In other words, we can allocate a 64 KB block of memory and then split it into 16 4 KB chunks. It means we can allocate 524,288 memory blocks (ranging in size from 1 byte to 4 KB) within a 2 GB address space. Of course, this isn't as good as 134,217,728 memory blocks in a 64-bit application, but it's already sufficient for practical operation of 32-bit applications - provided they don't allocate too much memory.

Therefore, if the requested block size is smaller than the page size (4 KB), VirtualMM will classify it as a "small block". These blocks will be grouped together in a single pool.

It's important to understand that since all "small blocks" are grouped in a single memory area, there will be no unaccessed memory pages between them — which is the case for all other (regular, large) memory blocks. It means VirtualMM won't be able to catch buffer overflows in "small blocks" — at least not in hardware. However, VirtualMM adds guard values before and after "small block"s to catch buffer overflows in software, just like regular debugging memory managers do.

It also means the memory consumption of your application will increase significantly when using VirtualMM — this memory will be spent on guard pages at the edges of allocated memory blocks, as well as on rounding up the block size to the allocation granularity. It means if you want to debug your application with VirtualMM, you need to ensure that any memory issue surfaces as soon as possible. The sooner the problem is detected, the less likely your application will crash with an out-of-memory error.

Where can I download VirtualMM?

The VirtualMM debugging memory manager is included with EurekaLog. You can find it in the \Extras subfolder of your EurekaLog installation.

If you don't have EurekaLog, you can use the GetIt package manager on IDEs since RAD Studio XE8.

If you don't have EurekaLog and you are using RAD Stduio XE7 or earlier - down to Delphi 6 (in other words, you don't have the GetIt package manager), you can download VirtualMM separately from the EurekaLog website.

It should be noted that the concepts of the VirtualMM debugging memory manager were implemented in another debugging memory manager: SafeMM, presented by Mark Eddington at the DelphiLive conference. SafeMM was presented as part of the DelphiLive conference materials, so it was not possible to download it directly. The conference materials are no longer available, but its source code has been posted on Code Central. Later, the source code was adapted to newer Delphi versions (at the time). However, SafeMM was written as a "proof of concept" and was not supported or developed. Therefore, if you are looking for where to download SafeMM, you can download VirtualMM instead. VirtualMM has more features.

How to install VirtualMM?

VirtualMM does not have a dedicated installer and is distributed:

[For EurekaLog 7.14 and above] with EurekaLog. In this case: "installing VirtualMM" consists of "installing EurekaLog". After installation: VirtualMM can be found in the \Extras subfolder of the EurekaLog installation folder. This folder will already be included in the search paths of installed IDEs; nothing else is required;
[For XE8 and above] via the GetIt package manager:

Click on image to enlarge
[Universal, Delphi 6 and above] as a ZIP archive with Delphi source code files. To install VirtualMM in this format: simply unzip the archive to any folder and specify that folder in the search path for the project in which you want to use VirtualMM:

Click the image to enlarge

How do I add (connect) VirtualMM to a project?

Simply add VirtualMM as the first module in your project's .dpr file, for example:

program Project1;

  uses
    VirtualMM, // - added
    Vcl.Forms,
    Unit1 in 'Unit1.pas' {Form1};

{$R *.res}

begin
  Application.Initialize;
  Application.MainFormOnTaskbar := True;
  Application.CreateForm(TForm1, Form1);
  Application.Run;
end.

It's very important to specify VirtualMM first in the uses clause. If you don't specify it first, some other code will be initialized first, which will likely allocate memory through the built-in memory manager. Therefore, when VirtualMM gets to initialization, it won't be able to set itself as the memory manager, since memory was already allocated through the built-in memory manager.

If you get an error like this when compiling your project:
[dcc32 Fatal Error] Project1.dpr(4): F2613 Unit 'VirtualMM' not found
it means you haven't added the VirtualMM source code folder to your project's (or IDE's) search path. See the "How do I install VirtualMM?" section above.

The following warning will be displayed in IDE's "Messages" output when a project is built:

[DCC Warning] VirtualMMOptions.inc(51): W1054 WARNING: VirtualMM is ON, do not use this build on production

This is an additional warning reminder that you built the program with VirtualMM. This reminder is needed so you don't accidentally submit this version of the program to production. In other words, it is "as designed". This is how it should be.

How to configure VirtualMM?

VirtualMM consists of three files:

VirtualMM.pas - the main source code. You include this unit in the project (see above). This file does not need to be edited.
VirtualMMDefs.inc - contains conditional symbols required for proper compilation in all supported IDEs (from Delphi 6 to the latest available IDE, which at the time of writing is RAD Studio 13 Florence). This file does not need to be edited.
VirtualMMOptions.inc - contains user options that allow you to change the behavior of the memory manager. This is the file you need to edit to configure VirtualMM.

The option is enabled if you uncomment its line, for example:

{$DEFINE USE_SMALL_BLOCKS}

The option is disabled if you comment its line, for example:

// {$DEFINE USE_SMALL_BLOCKS}

Specifically, VirtualMM supports the following options:

USE_SMALL_BLOCKS (enabled by default): Enables support for "small blocks", as discussed above. Enabling this option allows you to conserve memory, which is necessary for running 32-bit applications. 64-bit applications have a huge address space, so running out of blocks is less of a problem. It's worth noting that "small blocks" are a compromise, a workaround. Not all types of checks can be implemented with "small blocks", as discussed above. Usage recommendations: enable this option for 32-bit applications, disable it for 64-bit applications. Enable it if your 64-bit application starts crashing due to out-of-memory errors.
PROTECT_OVERFLOW (enabled by default): instructs VirtualMM to protect against buffer overflows. In this case, all allocated memory will be aligned so that unavailable memory begins after the end of the allocated block. Thus, writing beyond the end of the allocated buffer will immediately throw an Access Violation exception. Disable this option only for special cases (see below). Only one of the PROTECT_* options can be enabled at a time.
PROTECT_UNDERFLOW: Instructs VirtualMM to protect against buffer underflows. In this case, all allocated memory will be aligned so that unavailable memory begins immediately before the beginning of the allocated block. Therefore, writing beyond the allocated buffer will immediately throw an Access Violation exception. Enable this option only to detect problems with writing before the block. Such problems are quite rare; usually, the opposite occurs. Only one of the PROTECT_* options can be enabled at a time.
PROTECT_RANDOM: Instructs VirtualMM to randomly enable PROTECT_OVERFLOW or PROTECT_UNDERFLOW (on each memory allocation). This is rarely needed — only if you have multiple buffer overflow/underflow issues (on both sides of memory blocks). Probably the best solution is to look for problems one at a time: first PROTECT_UNDERFLOW, then PROTECT_OVERFLOW (or vice versa). Only one of the PROTECT_* options can be enabled at a time.
ALLOCATE_TOP_DOWN (enabled by default): Tells VirtualMM to allocate memory from top to bottom. Enabling this option slows down performance slightly, but allows you to catch Integer/Pointer conversion bugs faster. Typically, you should leave this option enabled. Note: a 32-bit application must be marked as high-address aware (the IMAGE_FILE_LARGE_ADDRESS_AWARE flag must be set) for this option to be useful.
CATCH_USE_AFTER_FREE: This is a special option that allows you to find the bug of accessing freed memory in an environment where memory is frequently reused. We will discuss it in more detail below. Enabling this option tells VirtualMM to never to free memory (*). As you can imagine, enabling this option will lead to catastrophic memory usage growth, especially if you frequently "allocate" and "free" memory. For this reason, this option is useless in 32-bit applications: a 32-bit application will crash with an "out of memory" error before it even gets to the problem. Enable this option only in 64-bit applications and only to detect issues accessing freed memory that are otherwise undetectable.
NeverUninstall: Tells VirtualMM not to uninstall itself when the application exits. This option is only needed for compatibility with some older IDEs that have a bug: attempting to free memory after the application has "terminated."
VirtualMMAlign (16 by default): Specifies the alignment of all allocated memory. In other words, the allocation granularity. This value must be a multiple of 8 bytes for 32-bit applications and 16 bytes for 64-bit applications: i.e. 8 (32-bit only), 16, 24 (32-bit only), 32, 40 (32-bit only), 48, etc. Larger values will result in increased memory usage, since some memory will be wasted filling the gaps between blocks. Furthermore, large values will also significantly worsen buffer overflow detection (the PROTECT_OVERFLOW option) - see discussion below. We recommend setting this to the minimum value your application can handle. This option also has two special values: 1 to disable alignment completely (formally prohibited in Delphi, as this may crash the application) and 0 to use dynamic alignment obtained from the System.GetMinimumBlockAlignment function.

What problems does VirtualMM solve?

Let's look at how VirtualMM can help us diagnose the memory bugs we discussed above.

Referencing already freed memory

We had the following examples:

var
  P: Pointer;
begin
  P := VirtualAlloc({...}); // "allocate" memory for P
  P^ := {...};              // do something (work) with P
  VirtualFree(P);           // finished working, "free" memory

  // BUG: accessing already freed memory
  P^ := {...}; // this line will ALWAYS throw an Access Violation exception with VirtualMM
end;

and

var
  L: TList;
begin
  L := TList.Create; // "create" the object
  L.Free;            // "free" the object

  I := L.Count;      // this line will ALWAYS raise an Access Violation exception with VirtualMM

Since VirtualMM actually frees memory when it "frees" it, the memory becomes inaccessible after it's "deleted", so any attempt to access such memory will result in an Access Violation exception — whether it's a write or (more interestingly) a read. Note that VirtualMM will allow you to detect memory bugs immediately, in situ, rather than much later, as would happen with a regular debugging memory manager. Furthermore, VirtualMM will also catch attempts to read from already deleted memory, whereas typical debugging memory managers usually can't help with this bug.

Buffer overflow

We had this example:

var
  Buffer: PInteger;
begin
  GetMem(Buffer, Count * SizeOf(Integer)); // "allocate" memory for Count Integers
  for X := 0 to Count do                   // BUG: should be Count - 1
  begin
    Buffer^ := 0;                          // the last step will raise an Access Violation exception with VirtualMM in PROTECT_OVERFLOW mode
    Inc(Buffer);
  end;

If the `USE_SMALL_BLOCKS` option is disabled

If the PROTECT_OVERFLOW option is enabled in VirtualMM (or this option was selected with the PROTECT_RANDOM option), VirtualMM will allocate one inaccessible memory page immediately after the memory block, so an attempt to read or write beyond the block will throw an Access Violation exception.

Of course, if the PROTECT_UNDERFLOW option was enabled (or this option was selected with the PROTECT_RANDOM option), VirtualMM will allocate one inaccessible page immediately before the memory block. Since the memory page granularity is 4 KB, the end of the allocated block will most likely not fall exactly on a page boundary. It means the code will execute successfully in this case, without raising an Access Violation exception. The exception will only occur if you continue "stepping" forward and reach the end of the current page.

There's one subtlety here. Delphi has a convention that any memory manager, whether standard or custom, must return memory aligned to at least 8 bytes. More is possible (for example, 32), but not less than 8. For example, Delphi 7 aligns memory to 8 bytes, while RAD Studio 13 Florence aligns it to 16 bytes. VirtualMM, however, aligns memory to whatever you specify. It could be 8, 16, or 32. But the default is 16 (see the VirtualMMAlign option above).

Why are we saying this? Obviously, if you align the start of a block to a certain boundary, the end of that block will be "random". For example, if you align to 8 bytes and allocate a 1-byte block, you could allocate it at, say, 16k - 8, but then the memory block would span addresses from 16k - 8 to 16k - 7 (exactly 1 byte) – which is 7 bytes less than the nearest page boundary (16k). It means these seven bytes of "padding" will have the same hardware protection attributes as the allocated memory block, i.e., they will be readable and writable. In other words, a buffer overflow of up to 7 bytes cannot be immediately detected. However, a buffer overflow of 8 or more bytes will affect the next memory page (without access), which will trigger an Access Violation exception.

For this reason, it is important to use the smallest possible memory allocation granularity.

However, VirtualMM always places guard values before and after a memory block (if there is the aforementioned empty space), so although an attempt to read immediately after a block will always succeed, an attempt to write after a block will be detected when the memory block is freed. Thus, VirtualMM will behave like a regular debugging memory manager. In this case, an EAssertionFailed exception will be raised with the message ReleaseLargeBlock: Block Overflow (or "Block Underflow"). In general, any assert exceptions from VirtualMM indicate a memory bug: they indicate that someone has violated (overwritten) some protective or control structures (headers) of memory blocks, i.e., it is a clear bug of writing to an invalid address. Just in case, we'll clarify again that we're only talking about accesses within the memory block alignment padding. Access attempts outside the alignment padding will be detected immediately (by hardware).

If you can't find a buffer overflow problem, you can try using formally unsupported align values, such as 1 (i.e., no alignment at all), and hope that your application can run in this mode. In this case, there will be no alignment padding, and therefore, hardware protection will operate immediately at the memory block boundary.

If the `USE_SMALL_BLOCKS` option is enabled

If the PROTECT_OVERFLOW option is enabled in VirtualMM (or this option was selected with the PROTECT_RANDOM option) and the block size is less than the page size (4 KB), then VirtualMM will place the guard value immediately after the memory block, so that although an attempt to read beyond the block will always succeed, an attempt to write beyond the block will be detected when the memory block is "freed". Thus, VirtualMM will behave like a regular debugging memory manager. In this case, an EAssertionFailed exception will be raised with the message ReleaseSmallBlock: Block Overflow (or "Block Underflow").

If the block size is larger than the page size (4 KB), VirtualMM will behave as in the case "If the USE_SMALL_BLOCKS option is disabled" above, i.e., it will allocate guard pages and detect a read/write beyond the block immediately (with the above-mentioned adjustment for the memory block alignment padding).

Calling a static method of a deleted object

Since calling a static method does not depend on the object's data, VirtualMM cannot help with this case. However, since the called static method most likely does something with the object (otherwise it would be a function, not a method), the first attempt to read or write to the object will throw an Access Violation exception. For example:

var
  L: TList;
begin
  L := TList.Create; // "create" the object
  L.Free;            // "free" the object

  I := L.IndexOf(P); // will always raise an Access Violation within a method with VirtualMM

Therefore, VirtualMM will help detect the bug as close to its origin as possible.

Calling a dynamic method of a deleted object

Calling virtual methods is simpler: the object's memory will not be accessible after the object is "deleted", so calling a virtual method will always raise an Access Violation when attempting to read the method's address from the object. For example:

var
  S: TStringList;
begin
  S := TStringList.Create; // "create" the object
  // Working with S
  S.Free;                  // "free" the object

  I := S.Count;            // will always raise an Access Violation when calling a virtual method with VirtualMM

Memory reuse

We had this code:

var
  S1, S2: TStringList;
begin
  S1 := TStringList.Create; // "create" the object
  // Working with S1
  S1.Free;                  // "free" the object

  S2 := TStringList.Create; // "create" the object

  I := S1.Count;            // logically - a bug, but will always succeed since S1 = S2

Can VirtualMM do anything in this case? Yes, it can. But only in 64-bit applications.

To do this, you need to enable the CATCH_USE_AFTER_FREE option. Enabling this option will prevent VirtualMM from ever freeing memory when "freeing". It means that if we immediately "create" a second object (S2 in the example above), it will never be allocated at the same address as the first object (S1 in the example above), since the memory for the first object will be forever occupied. In other words, S1 is no longer equal to S2, and therefore, calling S1.Count will throw an Access Violation exception, since the memory of S1 will be inaccessible.

As you can imagine, never freeing memory is a very aggressive strategy that can only work if you have a HUGE amount of free memory. In particular, enabling the CATCH_USE_AFTER_FREE option in 32-bit applications is pointless, since a 32-bit application will crash almost immediately with an out-of-memory error, before reaching the code that contains the bug. But even in 64-bit applications, it makes sense to try to ensure that the memory bug you're trying to catch occurs as early as possible.

var
  S1, S2: TStringList;
begin
  S1 := TStringList.Create; // "create" the object
  // Working with S1
  S1.Free;                  // "free" the object

  S2 := TStringList.Create; // "create" the object

  I := S1.Count;            // will always raise an Access Violation when calling a virtual method with VirtualMM and the CATCH_USE_AFTER_FREE option is enabled.

Recommendation for this option: keep it disabled. If you can find a bug without enabling this option - do so. Enable this option only in 64-bit applications and only if you can't find the bug otherwise.

When should you use VirtualMM?

Since VirtualMM is a rather special debugging memory manager, it should only be used in extreme cases where you can't find a memory bug otherwise. Most often, these will be situations where you mistakenly read from "freed" memory.

Less often, but also frequently, these will be situations where you write to "freed" memory. The main reason for choosing VirtualMM in these cases would be that debugging memory managers detect the problem too late (after it occurs), while VirtualMM can do this immediately.

When NOT to use VirtualMM?

Since VirtualMM is a rather special debugging memory manager, it should never be used in a release (production) for the following reasons:

Slow operation due to the need to make a kernel call for each memory "allocation" and "freeing";
High memory consumption:
- Rounding up to the page size (4 KB);
- Allocation of guard pages (buffer overflow/underflow protection);
- Memory only grows, but does not shrink, when the CATCH_USE_AFTER_FREE option is enabled.

This is why, when building a project with VirtualMM, the following message will appear in the message window:
[DCC Warning] VirtualMMOptions.inc(51): W1054 WARNING: VirtualMM is ON, do not use this build on production
This is done intentionally to prevent you from accidentally compiling your program for production with VirtualMM.

Using VirtualMM with EurekaLog

Although VirtualMM is part of EurekaLog, it is not related to EurekaLog and does not share source code with it. It is a standalone product that can also be downloaded as a standalone download.

EurekaLog includes a memory manager filter (add-on) that performs several memory checks. These checks largely overlap with VirtualMM, so while they can be used together, there's little point in doing so. After all, the point of VirtualMM is to place hardware protection at memory block boundaries, and by enabling memory checks in EurekaLog, you'll be pushing those boundaries to accommodate EurekaLog debug data — which, as you might guess, will impair VirtualMM's ability to immediately report memory bugs (as soon as they occur). Since this ability is the primary reason you'd want to use VirtualMM, it shouldn't be interfered with. That is: if you use VirtualMM in a project with EurekaLog, all memory checks in EurekaLog must be disabled (the "Enable extended memory manager" option must be disabled, and the "When memory is released" option must be set to "Do nothing").

On the other hand, note that VirtualMM is not a replacement for memory checks in EurekaLog:

First, EurekaLog has a memory leak detection feature, which VirtualMM lacks;
Second, EurekaLog can report memory issues in a more accessible way (for example, two call stacks will be shown for memory double free errors);
Third, EurekaLog is designed for reporting from user machines (release/production), while VirtualMM can only be used for development.

Note that VirtualMM never explicitly reports memory bugs as "this memory bug" exception: it will always be either EAccessViolation or EAssertionFailed - unlike EurekaLog, which always tries to report precise information, for example, EUseAfterFree, EBufferOverflowError or EDoubleFreeError. Actually, the essence of using VirtualMM is precisely the hardware protection (i.e. the EAccessViolation exception). At the same time, in some cases, EAccessViolation/EAssertionFailed exceptions will be raised within the code of VirtualMM itself (i.e. the memory manager). For example, when an invalid or corrupted block of memory is passed. The problem here is that the Delphi debugger is not always able to correctly build the call stack if you are inside a memory manager function. For example, if VirtualMM detects a buffer overflow when freeing a block of memory, it will throw an EAssertionFailed exception with 'Block Overflow', but the IDE may show an incomplete or truncated call stack, like this:

KERNELBASE.RaiseException
@Assert
VirtualMM.ReleaseLargeBlock or VirtualMM.ReleaseSmallBlock
VirtualMM.VirtualFreeMem
@FreeMem
and here the call stack either ends or contains functions further up the stack, and the one that directly calls FreeMem is missing.

Needless to say, this makes it very difficult to find the problem.

Yes, if you're proficient in debugging, you can build the call stack manually. But not everyone can do this, and it's quite a complex operation. Or you can use EurekaLog: EAccessViolation/EAssertionFailed - these are regular exceptions that will be caught by EurekaLog, and if you don't suppress them with code like:

try
  FreeMem(P);
except
  // Do nothing
end;

then they will be processed by EurekaLog, which will be able to show an exception report with the full stack (unless you changed the stack tracing method to any frame-based method).

So, the recommended workflow is:

DEBUG/Development stage:
1. You turn off all memory checking in EurekaLog (or disable EurekaLog altogether, although this is not recommended for the reason stated above);
2. You add VirtualMM to the project and configure it;
3. You search for and fix memory bugs in the application (e.g., stress/load testing).
RELEASE/Production stage:
1. You remove VirtualMM from the project;
2. You enable and configure memory checks in EurekaLog;
3. You test the application (test exceptions and memory bugs);
4. You deploy the application;
5. You collect bug reports and fix any bugs found. If you find a memory bug that you can't diagnose, you're using VirtualMM again (while debugging).

What should I do if my app crashes with out-of-memory errors when using VirtualMM?

As we've said many times before: using VirtualMM leads to increased memory usage. If your app throws an EOutOfMemory exception, how can you fix it?

Follow these steps from top to bottom until the error disappears:

Modify the app to 64-bit. This is the most reliable method;
Rearrange the code so that the memory bug occurs as early as possible. Remove all non-essential code;
Disable CATCH_USE_AFTER_FREE;
Enable USE_SMALL_BLOCKS;
Revise your application logic. Allocate fewer memory blocks. For example, use a dynamic array of blocks instead of allocating single small blocks.

Notes

(*) When we talk about memory, we greatly simplify things. By "memory" we mean the application's address space. For simplicity, we don't distinguish between reserved (RESERVE) and committed (COMMIT) memory. For example, the words "allocated memory" can mean either "reserved memory" or "committed memory" - depending on the context.
(**) 64 KB is the default value on many systems. However, this value may be different for your specific system. It is obtained from the dwAllocationGranularity field of the SYSTEM_INFO structure. Throughout the text, we talk about 64 KB, but you should understand that it is not a constant.
(***) Since VirtualMM is also a debugging memory manager, from here on, by "debugging memory managers" we will only mean "typical"/"regular"/"all other" memory managers, not including VirtualMM. To avoid having to write the exception "typical debugging memory managers other than VirtualMM" every time, we'll simply write "debugging memory managers" when referring to all other managers excluding VirtualMM.
(****) 4 KB is the default value on many systems. However, this value may be different for your specific system. It is obtained from the dwPageSize field of the SYSTEM_INFO structure. Everywhere in the text it says 4 KB, but you should understand that it is not a constant.

EurekaLog 7.14 is out

2025-09-15T20:19:00.003+01:00

We are pleased to announce the availability of the new 7.14 version.

EurekaLog is a tool for Delphi and C++Builder that gives your application the power to catch every exception and memory/resource leak, generating a detailed log of the call stack (with unit, procedure and line number), optionally sending you a copy of each log entry via email or the Web via the most used Web Bug-Tracking tools (as Mantis, BugZilla, FogBugz, JIRA, YouTrack, Redmine, Exceptionless, GitLab, and GitHub).

EurekaLog represents the most advanced exception and memory leaks logger technology available for Delphi/C++Builder developers.

To learn more about EurekaLog, please visit our website at:
https://www.eurekalog.com

To download a demo, please visit:
https://www.eurekalog.com/downloads.php

If you would like to purchase a new license, please visit:
https://www.eurekalog.com/buy.php

Changes in 7.14 build:

Added: Added RAD Studio 13 Florence support
Added: Workaround to report exceptions with invalid CPU context
Added: The new "VirtualMM" debugging memory manager (replacement for SafeMM), see \Source\Extras\
Fixed: Bugzilla sender fail to post new bug
Fixed: Few multithreading issues
Fixed: Minor call stack improvements
Fixed: Minor performance improvements

See full change log here.

EurekaLog and Windows Service Applications

2025-08-28T10:58:00.000+01:00

We were contacted by a customer who wondered how EurekaLog works in service applications, considering it has options like freeze detection, while service apps don't have main thread.

A service application has main thread like any other application. Main thread is a thread which executes app's entry point (begin/end in your .dpr file). Its ID is stored in the RTL's MainThreadID global variable.

Now, if we are talking about VCL's service apps - the main thread is not doing any heavy lifting in these apps. It runs the TServiceApplication.Run, which basically waits for service to exit.

There are two ways to implement a service:

Either a loop inside the ServiceExecute event (with calling the TServiceThread.ProcessRequests method in the loop);
Or spawn worker background threads inside the ServiceStart event and stop them in the ServiceStop event.

However, no matter which design you choose - all events (ServiceExecute, ServiceStart, etc.) are already called from a background thread. Main thread does not call any events.

The picture is like this (it is not a call stack, it is more like sequence of calls):
[Main thread] -> Application.Run -> [TServiceStartThread] -> StartServiceCtrlDispatcher -> Application.DispatchServiceMain -> TService.Main -> RegisterServiceCtrlHandler -> TService.DoStart -> [TServiceThread] -> TServiceThread.OnStart -> .OnExecute -> .OnStop
Things in [] indicate a new thread was spawned. As you can see, its [Main thread] -> [TServiceStartThread] -> [TServiceThread] -> your code. You have at least two background threads.

From MSDN:

When the service control manager starts a service process, it waits for the process to call the StartServiceCtrlDispatcher function. The "main thread" of a service process should make this call as soon as possible after it starts up (within 30 seconds). If StartServiceCtrlDispatcher succeeds, it connects the calling thread to the service control manager and does not return until all running services in the process have entered the SERVICE_STOPPED state. The service control manager uses this connection to send control and service start requests to the main thread of the service process. The "main thread" acts as a dispatcher by invoking the appropriate HandlerEx function to handle control requests, or by creating a new thread to execute the appropriate ServiceMain function when a new service is started.

As you can see: the VCL does not follow this description toe to toe - it uses one additional intermediate background thread to call the StartServiceCtrlDispatcher function. However, even if VCL would call the StartServiceCtrlDispatcher function on its main thread, the TService still creates a TServiceThread background thread to call your events. So your code is never executed in the main thread in VCL service apps.

But if your code is never executed in the main thread - it does not mean there is no main thread! There is - it is just not calling your code.

Since even empty VCL service application has at least 3 threads (main thread, TServiceStartThread, TServiceThread): it is already a multithreaded application - even if you don't create your own (additional) threads. Usually EurekaLog has to be enabled for each background thread that you want to handle exceptions. If you are using default settings (like not disabling low-level hooks), the EAppService unit would detect when a new TServiceThread starts and enable EurekaLog for it automatically. However, it will not know about your own background threads.

Therefore:

[Optional] If you disable the low-level hooks in EurekaLog - you have to manually activate EurekaLog for TServiceThread like so:

procedure TService1.ServiceStart(Sender: TService; var Started: Boolean);
begin
  {$IFDEF EUREKALOG}
  SetEurekaLogStateInThread(0, True); // activate EurekaLog for this thread
  {$ENDIF}
  
  // your own code here
end;

[Mandatory] If you spawn your own background threads (like in the ServiceStart event) - you have to activate EurekaLog for these threads by any available means. One possible example:

procedure TService1.ServiceStart(Sender: TService; var Started: Boolean);
begin
  {$IFDEF EUREKALOG}
  SetEurekaLogStateInThread(0, True); // activate EurekaLog for the TServiceThread thread
  {$ENDIF}
  
  FWorkerThread := TMyThread.Create(False); // create a background worker thread
end;

procedure TMyThread.Execute;
begin
  {$IFDEF EUREKALOG}
  SetEurekaLogStateInThread(0, True); // activate EurekaLog for the TMyThread thread
  {$ENDIF}
  
  // your own code here
end;

Now, about the freeze detection feature. It works by sending a message to the main thread and checking if it gets a reply in time. It uses the main thread specifically because it is the thread which performs the message loop processing in VCL Forms apps. If app's UI is hang, then the main thread will not reply in time, so the freeze detection can say "app is not responding".

As you can see, this logic is completely useless in service apps, because service apps don't have windows (UI). It is even indicated in the option's name: "Activate UI hang detection".

However, the freeze detection can also use new Windows Vista API to detect explicit deadlocks between two threads. It will work in any app, assuming it runs on Windows Vista or later. So, this feature can be useful even in service apps. Well, assuming your freeze detection timeout is less than system timeout for services. Otherwise the system would terminate the service before freeze detection would have time to react.

Read more about hangs and deadlocks with EurekaLog.

How to read bug reports

2025-08-13T15:29:00.004+01:00

We were contacted by a customer who used a previous major version of EurekaLog and upgraded to the EurekaLog 7 recently. He said his application crashes on exit. He attached a bug report file produced by EurekaLog. The bug report was about access violation exception.

The customer did not actually ask any question. He just stated his app crashes. It was unclear if the customer is seeking help fixing a bug in his application, asking why there was no bug reported previosly, or he thinks it is some sort of "false-positive" bug report.

Well, any access violation exception is a definitive bug in the application, which can not be false-positive. It is the issue that needs to be fixed.

As for why there was no bug report before: many memory-related bugs are sensitive to how memory is allocated, so some changes in code may hide or reveal a memory bug. EurekaLog 7 does have memory checks - and these are enabled by default, unlike previous EurekaLog major versions. If you did not run your application with memory checks before - your application may have memory bugs hidden. So if you add EurekaLog 7 to your application, a previosly hidden bug may be revealed. We have many examples shown in stories from our customers.

Now, about troubleshooting the issue: we don't actually provide such a service. Yes, we offer support for our own product (EurekaLog), but debugging bugs in your application is outside the scope of our support. Currently we don't offer such consulting service. However, if it is not much trouble - we would gladly assist you unofficially.

So, we started by looking at the call stack from customer's bug report. Scrolling down the call stack - we can see his application is shutting down and cleaning up components:

...

Classes.TComponent.DestroyComponents

Forms.DoneApplication

SysUtils.DoExitProc

System._Halt0

Unit1.Form1.btnCloseClick 3854[1]

...

(all names from customer's code here and below were replaced with generic names)
First thing to notice is that functions from RTL do not have line numbers. Typically this happens because you did not configure your project for debugging. Specifically, you need to enable the "Use Debug DCUs" option. However, the customer uses Delphi 5, which does not have line number information for debug DCUs, so there is nothing he can do.

Next, walking the stack up, we can see some TContosoViewPanel class is being deleted as part of this process:

...

Forms.TScrollingWinControl.Destroy

Contoso.TContosoViewPanel.Destroy 291 [16]

Controls.TWinControl.Destroy

...

The TContosoViewPanel class deletes some other class/component as part of its destruction:

...

Controls.TControl.Destroy

System.TObject.Free

Controls.TWinControl.Destroy

...

Unfortunately, the call stack misses line numbers, but since the Free method is called from the TWinControl.Destroy destructor - we are talking about deleting owned components. In other words, the TContosoViewPanel class owns some component, and it deletes this component as part of its own destruction.

When a component is deleted, it sends a notification about it being deleted:

...

Forms.TCustomForm.Notification

Classes.TComponent.RemoveComponent

Classes.TComponent.Destroy // owned component

...

This notification is being received by the (same?) TContosoViewPanel class:

...

Classes.TList.Get // crashes here

Contoso.TContosoViewPanel.Notification 1732 [25]

Classes.TComponent.Notification

...

Summary: it is a pretty clear picture indicating a bug in the TContosoViewPanel class. Looks like the TContosoViewPanel class owns some other component, but it does not expect this component to be deleted at the Contoso.TContosoViewPanel.Notification 1732 [25] line - which can happen during shutdown.

The TList.Get method is really simple:

function TList.Get(Index: Integer): Pointer;
begin
  if (Index < 0) or (Index >= FCount) then
    Error(@SListIndexError, Index);
  Result := FList^[Index];
end;

Let's take a look at the "Assembler" tab from the bug report to see if we can squeeze some extra information out of bug report:

00459C30 53 PUSH EBX ; start of the TList.Get
00459C31 56 PUSH ESI
00459C32 8BF2 MOV ESI, EDX
00459C34 8BD8 MOV EBX, EAX ; the EAX register is Self, it is stored into the EBX register
...
; Result := FList^[Index];
00459C4E 8B4304 MOV EAX, [EBX+4] ; the FList field is read into the EAX register
00459C51 8B04B0 MOV EAX, [EAX+ESI*4] ; -- EXCEPTION

So, the code from the TList.Get reads its FList field (a pointer to an array) - which succeeds. And then it tries to dereference it - which fails.

Let's also take a look at the exception's message: "Access violation at address 00459C51 in module 'Project1.exe'. Read of address 042C7D58". Match the exception message with disassembler output: obviosly the 042C7D58 address from the message is the result of [EAX + ESI * 4] from the disassember. We can learn what these registers are from the bug report's "CPU" tab:

EAX: 00D5B2AC

ESI: 00D5B2AB

The EAX is supposed to be an address of the dynamically allocated memory (array). The ESI is supposed to be an index in the array. As you can see, the ESI is clearly incorrect (it should be something like 0, 1, 2, etc.). Additionally, these two values seems to be aweful close to each other, which may indicate both EAX and ESI are incorrect and are part of something else.

We can take a look at the "Modules" tab: the Project1.exe is loaded at $00400000 and have a size of 14749696 or $00E11000. $00400000 + $00E11000 = $01211000 - which is more than $00D5B2AC. It means that $00D5B2AC and $00D5B2AB are code addresses. In other words, $00D5B2AC can't be address of dynamic memory, because it is a pointer to code in the app.

Сorollary: both EAX (pointer to an array) and ESI (index of the array) are incorrect and are, in fact, pointers to code. Possibly - functions.

That's about all info that you can extract from the bug report. What's next? Well, assuming you have the same application that was used to produce the bug report:

You can run your program;
Pause it;
Use View / Debug Windows / CPU;
Right click on the code (disassembler view);
Select "Goto address...";
Enter $00D5B2AC (or $00D5B2AB);
See where this will take you.

Alternatively, you can use the Start / Programs / EurekaLog / Tools / Address Lookup tool to see what source code corresponds to the mentioned addresses.

While we don't have the customer's source code, we can make a guess: both TList and its index are read by the Contoso.TContosoViewPanel.Notification from some object. And that object is already deleted at this moment. The customer has access to its source code, so he can easily check where these values are coming from.

When an object is deleted, EurekaLog fills that object with some values. Some of these values are pointers to the DeadObjectVirtualMethodCall function from the EMemLeaks unit. This function will be called when someone will try to call a virtual method on the deleted object. Since $00D5B2AC and $00D5B2AB values are code addresses - I would speculate one of them is a pointer to the DeadObjectVirtualMethodCall function, which further confirms the Contoso.TContosoViewPanel.Notification accesses an already deleted object.

Another way to tackle this is to place breakpoints on the mentioned lines 291 and 1732 of the Contoso.pas file. And walk step-by-step watching for the mentioned bug.

The customer replied back informing us he was able to find and fix the bug in his application armed with this information.

See also: What can you do with the "Assember" tab in bug reports? Is it even useful?

P.S. Read more stories like this one or read feedback from our customers.

Using EurekaLog with FastMM's full debug mode

2025-07-22T20:58:00.006+01:00

Were were contacted by a customer who claimed adding EurekaLog to his application prevented FastMM from doing its job. Specifically, FastMM could detect a problem like this:

SomeObj.Free;
SomeObj.SomeField := 1; // here: writing into released memory

but only in an application without EurekaLog. Once EurekaLog is added to an application, the FastMM no longer detects the "bad" code.

First of all: these kinds of checks highly depend on order in which memory operations are performed. FastMM does not detect writes into released memory as soon as the write operation completes. Instead, FastMM perform memory scanning check when your app request memory to be allocated in the same place - which can happen a lot later; or it could not happen at all.

For example:

SomeObj.Free;
SomeObj.SomeField := 1; // this will not be detected

TSomeObj.Create; // here: FastMM will allocate the object over the old memory block 
                 // and it will detect the old memory block was changed
                 // FastMM will crash here, even though there is no problem with the TSomeObj.Create

Additionally, you can tell FastMM to force-scan all released memory via the FastMM_ScanDebugBlocksForCorruption function at any time.

So one might think adding EurekaLog to an application changed the order of memory operations, so app's behaviour changed. However, that was not the case.

EurekaLog does not have its own memory manager. EurekaLog uses memory manager of your app - whatever it is set to. EurekaLog just adds some extra features to perform few memory checks. It is all done as layer on top of your existing memory manager. So, if you add FastMM to your project and then enable EurekaLog with memory checks - your app will use FastMM to allocate memory, while EurekaLog will use that memory to store extra data for memory checks.

The customer used FastMM 5. Unlike FastMM 4 (which enables full debug mode via conditional symbols), FastMM 5 can enable full debug mode by calling the FastMM_EnterDebugMode function. This function is so convenient, most people use it everytime, without realizing what it actually does.

The way full debug mode in FastMM works is that it is actually two different memory managers: the "release" one (FastMM_GetMem) and full debug mode one (FastMM_DebugGetMem). This was more obvious in FastMM 4, as enabling full debug mode required changing conditional symbols and a standalone DLL. So the FastMM_EnterDebugMode function simply switches the FastMM_GetMem to the FastMM_DebugGetMem. What people don't realize is that it is only possible if your app still uses FastMM_GetMem. Indeed: that way full debug mode will know how to release memory allocated by the FastMM_GetMem.

However, if memory manager was already set to something else (like EurekaLog's memory filter), the full debug mode would have no idea how to work with EurekaLog headers. Thus it won't be able to properly free memory allocated via EurekaLog. That is why the FastMM_EnterDebugMode function will no nothing when called in an application with EurekaLog (well, assuming it is called after EurekaLog's initialization). You can verify this:

if FastMM_EnterDebugMode then
  OutputDebugString('FastMM5: FULL DEBUG MODE ENABLED');

You will see this output in an app without EurekaLog, but not in app with EurekaLog.

That was exactly what customer did: he called the FastMM_EnterDebugMode function as first action in his project file (.dpr), but it is already too late: EurekaLog (as well as RTL and VCL) is already initialized at this point, so EurekaLog's memory filter is already set, therefore the FastMM_EnterDebugMode function will do nothing.

That was the reason: FastMM 5 did not detect anything, because FastMM's full debug mode was not enabled in the first place.

Is it possible to use FastMM 5 in full debug mode with EurekaLog?

Yes! All you need to do is to enable FastMM's full debug mode before EurekaLog sets its memory manager. In other words, the FastMM_EnterDebugMode function should be called before EMemLeaks unit initializes. Order of initialization matters. You can do this in at least two different ways:

If you open the FastMM5.pas file, you would see documentation for FastMM. It mentions this among other things:
The following conditional defines are supported:

- FastMM_FullDebugMode (or FullDebugMode) - If defined then FastMM_EnterDebugMode will be called on startup so that the memory manager starts in debug mode. If FastMM_FullDebugMode is defined and FastMM_DebugLibraryDynamicLoading (or LoadDebugDLLDynamically) is not defined then FastMM_DebugLibraryStaticDependency is implied.

- FastMM_FullDebugModeWhenDLLAvailable (or FullDebugModeWhenDLLAvailable) - If defined an attempt will be made to load the debug support library during startup. If successful then FastMM_EnterDebugMode will be called so that the memory manager starts up in debug mode.
which means you can add the FastMM_FullDebugMode (or FastMM_FullDebugModeWhenDLLAvailable) conditional symbol to your project's options. You probably want to add it into your "Debug" build configuration only. Now, build your project, and it will have FastMM 5 in full debug mode for the "Debug" build configuration, but production version of FastMM 5 for the "Release" build configuration.

That way the FastMM_EnterDebugMode function will be called when the FastMM5 unit is initialized - i.e. before the EMemLeaks unit is initialized.

Another way would be creating a FastMM5_FDM.pas unit like this:

unit FastMM5_FDM;

interface

implementation

uses
  FastMM5,
  Windows;

initialization
  if FastMM_EnterDebugMode then
  begin
    OutputDebugString('FastMM5: Full Debug Mode is enabled');
    
    {$IFDEF EnableMemoryLeakReporting}
    // Add the "EnableMemoryLeakReporting" symbol to your conditional defines to enable leaks checking
    FastMM_LogToFileEvents  := FastMM_LogToFileEvents  + [mmetUnexpectedMemoryLeakDetail];
    FastMM_MessageBoxEvents := FastMM_MessageBoxEvents + [mmetUnexpectedMemoryLeakSummary];
    ReportMemoryLeaksOnShutdown := True;
    OutputDebugString('FastMM5: Leaks Checks are enabled');
    {$ENDIF}
    
  end
  else
    OutputDebugString('FastMM5: Full Debug Mode is NOT enabled!');

finalization
  // Whatever sets these callbacks is already finalized at this point,
  // so we just clear/reset the callbacks just in case
  // (to avoid calling already finalized code).
  FastMM5.FastMM_GetStackTrace           := nil;
  FastMM5.FastMM_ConvertStackTraceToText := nil;
end.

Place this unit as your first unit:

uses
  FastMM5_FDM,
  {$IFDEF EurekaLog}
  EMemLeaks,
  EResLeaks,
  // ...

That way the FastMM_EnterDebugMode function will be called when the FastMM5_FDM unit is initialized - i.e. before the EMemLeaks unit is initialized.

Finally, if you disable EurekaLog's memory filter (the "Enable extended memory manager" option): EurekaLog will not change app's memory manager, so the FastMM_EnterDebugMode function can switch it at any time.

All mentioned methods will call the FastMM_EnterDebugMode function first, and then initialize EurekaLog's memory filter:

The FastMM_FullDebugMode will enable full debug mode at design-time;
The FastMM_FullDebugModeWhenDLLAvailable will enable full debug mode depending if the debug support library is present;
The FastMM5_FDM unit will enable full debug mode at the run-time.

except the last method, which will disable EurekaLog's memory filter entirely.

EurekaLog-enabled application starts up x2 times slower on Windows 2016

2025-07-08T12:47:00.006+01:00

We were contacted by a customer who claimed adding EurekaLog to his application increased application startup time by a factor of 2 - but only on PCs running Windows 2016. In other words, application startup takes about 6 seconds on Windows 2016, while taking only 3 seconds on any other OS.

The customer used a Process Monitor tool to observe that EurekaLog-enabled application creates a lot of *.tmp files. He wondered why that is, and if it could be a source of the issue.

Generally speaking, using a file in Windows is not slower than using a memory: that is because file operations are cached in memory. Writing, say, 1 Mb to a file does not mean your HDD will spin up to write 1 Mb of data, and your code continues only after the HDD finished his work. If you write some data into a file - it will be written in a memory buffer and dumped to a hard disk in background. In other words, if your application runs slower when creating/using a file - it is not because it is using a file, but because data size for the file is too large to fit in memory. So, if you replace a file with memory - the end effect would be the same: memory would be paged to disk because there is not enough RAM.

(There is an additional aspect when working with files: if you read/write very small chunks of data, so you call a lot of kernel's file functions. Calls to the kernel are slow - that is what may be causing the performance loss: it is about kernel calls, not about using a file. External factors may also play a role: for example, anti-virus could affect your file operations.)

EurekaLog uses temp files to offload large chunks of data from your address space so your application would have more free address space to run. For example, there is a lot of DLLs loaded into your process. EurekaLog has to provide debug information for each DLL in order to build reports including these DLLs. Naturally, this information has to be stored somewhere in a ready-to-use form. If we would store this info in memory, your application would have much less memory to run, as debug information tends to be very large. That is why EurekaLog creates debug information in temp files. However, this has nothing to do with performace. If we switch from files to memory - the end performance would be almost the same, but your own code would have less memory to execute.

We have the guide on troubleshooting performance issues in EurekaLog, so we naturally asked the customer to walk through this guide to check if startup on Windows 2016 is somehow different from startups on other OS - for example, perhaps there are additional exceptions being thrown when run on Windows 2016. However, the customer reported the guide did not help.

We asked the customer to capture a run-time log from EurekaLog for the "slow" PC and the "fast" PC, so we can compare two runs together. Basically, it means: compile your app with debug version of precompiled files (*.dcu) - which is already a default on modern IDEs. And pass the --el_debug command line switch. An el_debug.csl file will be created in app's folder. The file will contain everything EurekaLog is doing in the app. See the above mentioned article for more details on how to enable and use the run-time logging.

The produced *.csl files are compatible with the CodeSite file format, so you can use the CodeSite File Viewer tool - available as part of the freeware CodeSite Tools package (scroll to the bottom to find download link for the tools). Now you can open both *.csl files. This may take a while, since the CodeSite log format is mostly textual, so the CodeSide File Viewer will need some time to parse it. Typical logs from EurekaLog on application startup start from 2 Mb and are usually up to 10 Mb - depending on what your application is doing on startup. Opening a 10 Mb text file in the CodeSize File Viewer tool could easily take a few minutes.

Once the log is opened - you can use the "View" / "Select Columns" menu item to display Time Offsets:

Configuring the "Time" column

Since any Windows application runs multiple threads (even if your own code does not spawn any threads - the system will create few threads), it is a good idea to organize messages into individual threads, so you can inspect the main thread isolated from background threads:

Organizing log messages

Organizing messages could also take some time, be patient. Once messages are organized by threads - switch to the main thread tab:

Threads tabs will appear after organizing messages

Finally, we need to collapse all functions to make it easier to navigate the log. You can right-click on any log message inside log's view and select the "Collapse all" from the pop-up menu:

Collapsing all functions

This could take some time too.

Now we are ready to analyze the logs. Let's compare two startups:

Startup on the "Fast" PC

Startup on the "Slow" PC

As you can see: EurekaLog completed the startup in about 5 seconds on the "Fast" PC, and in about 11 seconds on the "Slow" PC. These values are slower than values reported by the customer, but it is because logging itself takes some time. Nevertheless you still can observe x2 time difference.

Let's open (expand) the "EurekaLog.Initialization" function to see what exactly it is doing:

Startup on the "Fast" PC

Startup on the "Slow" PC

Now we see something interesting: the "Slow" PC is actually running sligtly faster than the "Fast" PC! Notice how everything is completed in 0.343 seconds on the "Slow" PC compared to the 0.575 seconds on the "Fast" PC. However, there is still something on the "Slow" PC that causes the major delay. We need to dig deeper.

We would need to expand the "ExceptionLog7.Init" function, and then open the "EurekaLogInitialization" function, etc. We open a lot of functions until we arrive at the bottleneck code:

No bottleneck on the "Fast" PC

Bottleneck on the "Slow" PC

And again you can see the "Slow" PC is sligntly faster than the "Fast" PC, but not when inside the bottleneck code. The bottleneck code is the TELDebugInfoExports.GetExportList function from the EDebugExportBase unit. It takes about 0.5 seconds on the "Fast" PC and almost 4 seconds on the "Slow" PC - causing a major x8 times difference.

As you can see: this code loads debug information from the rtl290.bpl package. In this case: EurekaLog creates new debug information from the DLL (BPL) exports table since this package does not have any other debug information. If you scroll further - you will find a similar picture for the vcl290.bpl package. There will be more BPLs and DLLs listed, but times for these BPLs/DLLs will be similar.

The EDebugExportBase.TELDebugInfoExports.GetExportList function is essentialy a copy cycle:

  Count := ExportDir.NumberOfNames;
  SetLength(FNames.FNames, Count);
  for I := 0 to Count - 1 do
  begin
    Address := PDWORD(PtrUInt(Functions) + NameOrdinals^ * SizeOf(DWORD))^;
    UTF8Name := PAnsiChar(ABorImage.RvaToVa(Names^));
    if not TryUTF8ToString(UTF8Name, ExportName) then
      ExportName := String(UTF8Name);
    FNames.Add(ConvertAddress(Pointer(PAddress(Module) + Address)), ExportName);
    Inc(NameOrdinals);
    Inc(Names);
  end;

This cycle copies function names from the BPL/DLL exports table into a temp file buffer.

Well, assuming the rtl290.bpl package is the same on both "Slow" and "Fast" PC - it is not obvious how this code could produce such a large difference (almost x8 times). We asked the customer to rule out any possible external factors: such as anti-virus, but the customer reported he did not find anything.

One option is to pursue the issue further: launch a proper performance profiler to see what is taking so long in the code above. But there is another way: this bottleneck code is called because a package does not have a prepared debug information, so EurekaLog has to create one (from exports table). As you know: the fastest code is the one that is never called. The way to never call this code is to supply debug information for the package. Thankfully, modern IDEs come with *.jdbg files for each *.bpl file. *.jdbg file contains debug information in the JCL (JEDI) format. EurekaLog is able to read this format if you enable the corresponding debug information provider in EurekaLog's project options.

Once the customer deployed *.jdbg files to Windows 2016 PC - the performance problem disappeared. EurekaLog no longer needs to analyze the package and can use the prepared debug information from *.jdbg files.

P.S. Read more stories like this one or read feedback from our customers.

"Invalid EurekaLog configuration found" error

2025-05-13T13:26:00.004+01:00

Users of recent EurekaLog versions could receive the "Invalid EurekaLog configuration found" error message when they run their EurekaLog-enabled applications. The message looks like this:

Invalid EurekaLog configuration found.

Exception from the following module:
full-file-name-to-your-EXE-or-DLL
was catched in the following module:
full-file-name-to-your-DLL-or-EXE
Both modules have EurekaLog enabled, but EurekaLog code is not shared.

This is essentially the same error as:
- "Can''t assign a TFont to a TFont";
- "Invalid class typecast";
- reInvalidCast;
- "Run-time error 10".
etc.

Possible solutions:
- Do not allow exceptions from one module escape into another (recommended)
- Compile DLLs with Lightweight DLL profile, so your DLL will not have EurekaLog's code
- Compile EXE and DLL with run-time packages, so EXE and DLL will share EurekaLog's code

See our help for more information:
https://www.eurekalog.com/help/eurekalog/dll_using_eurekalog.php

What this check is

Previous versions of EurekaLog did not have this check, so users could configure their projects incorrectly and then contact us asking why various bad things happens or why EurekaLog behave incorrectly. That is why recent versions of EurekaLog perform this check explicitly to let users know they are doing something wrong.

The check is triggered when EurekaLog catches exception, which has EurekaLog information assigned, but this EurekaLog information does not come from EurekaLog itself! In other word, it comes from (a different) EurekaLog in a different module (EXE or DLL).

Naturally, you may get this error message only when you have EXE with EurekaLog and DLL with EurekaLog. You will never see this message if you have EXE without EurekaLog or DLL without EurekaLog.

What the problem is

We think that the message is pretty self-explanatory, but here is another example (without using EuerkaLog): suppose you have a function in DLL like this:

function CreateForm: TForm; stdcall; export;
begin
  Result := TMyForm.Create(nil);
end;

which is being called from EXE. As you should know, EXE and DLL both have each own code of VCL (by default). Which means there are DLL.TForm and EXE.TForm - two different things. So essentially you create "something" (object) in DLL and pass it back to EXE, which expects it to be EXE.TForm - but it is not: it is DLL.TForm.

The same thing is true for the reverse case: when EXE pass objects into DLL. For example, one may choose to pass EXE's Application or MainForm to DLL in order for DLL to display owned/child forms.

Such code is a bad design. You should never write such code.

We should note: such code can work - by coincedence: when all of the below conditions are true:

If both DLL and EXE are compiled with exactly the same version of VCL (or another code which implements passed objects) - so the object's layout in memory is the same for EXE and DLL;
If the caller does not check for the class explicitly (not using InheritsFrom, as operator, is operator, etc) on returned object and all of its properties (and properties of properties).
When at least one (any) condition is met:
- If the caller does not modify dynamic properties (strings, dynamic arrays, interfaces, etc.) of the returned object and does not call non-virtual object's methods that could do so. Basically, no (re)allocating memory in returned object.
- EXE and DLL share memory manager.

Did you notice? This list is basically saying that this code is WRONG:

procedure FuncInDLL; stdcall;
begin
  // your code
end;

Why? Well, imagine an exception happens in this function. What is exception in Delphi? Well, it is an object derived from the Exception class. In other words, an object (exception) created in DLL will be passed to EXE.

As you may suspect: most (?) Delphi DLLs are written in this way. And authors of these DLLs are saying: "this code works".

What they don't realize is that this code "works" by coincedence. For example, if a DLL will be loaded in EXE compiled with a different IDE version, memory layout of the Exception class may be different, so either EXE will crash trying to access properties of exception or it will corrupt exception object on write - leading to access violation and/or memory leaks. Another problem if EXE will decide to do something like:

try
  FuncInDLL;
except
  // This filter will not work, 
  // as the DLL.Exception class will not match the EXE.Exception class
  on E: Exception do 
  begin
    ShowMessage(E.Message);
    Exit;
  end;  
end;

or:

try
  FuncInDLL;
except
  // This will not work,
  // as EXE will manipulate memory for DLL
  Exception(ExceptObj).Message := 'Error in My DLL: ' + Exception(ExceptObj).Message;
  raise;
end;

So, when you have code like:

procedure FuncInDLL; stdcall;
begin
  // your code
end;

and it "works", and then you add EurekaLog to your DLL and EXE. EurekaLog creates objects containing collected information about exception (the TEurekaExceptionInfo class from the EException unit) and associate these exception info objects with exceptions.

So if you pass exception between DLL and EXE - you also pass EurekaLog's exception info object between DLL and EXE. And these objects are way more complex than exception objects, and EurekaLog do way more things that your code do with exceptions. So EurekaLog's code will certainly check exception info object's class (to see if an exception has associated exception's info) as well as modify exception info object. Which means: access violation, leaks, incorrect behaviour.

Solutions

The exact solution depends on what kind of DLL you are developing:

"Pure DLL"

If you are developing a pure DLL - that is: a DLL which can be loaded by any application - then the solution is to never let exceptions escape your DLL. In other words, each and every exported function must have an except block. An except block can be explicit like this:

function FuncInDLL: BOOL; stdcall;
begin
  try
    // your code
    Result := True; // only as an example
  except
    // handle exception here
    Result := False; // only as an example
  end;
end;

or it can be implicit like this:

procedure FuncInDLL; safecall; // notice "safecall"
begin
  // your code
end;

In either way, any DLL exception will be handled in the DLL itself and will not leave the DLL. The caller (EXE) will never receive exceptions from DLL, but rather some "failure" flag.

Read this article for more details.

"Delphi DLL"

If you are developing a Delphi DLL which can be used in Delphi applications only - then the solution is to use packages (BPLs).

One option is to convert your DLL to a BPL package. Another option is to compile EXE and DLL with BPL packages. The end result will be the same: both DLL and EXE will share common code and memory manager, therefore eliminating the problem.

So what you should do is to enable the "Link with runtime packages" option in your project's settings and ensure at least the rtl, vcl and EurekaLogCore packages are listed in the "Runtime packages" list. Using the rtl package will ensure using shared memory manager (so you can remove a dedicated shared memory manager from your DLL/EXE if you set up it previosly), while using the EurekaLogCore package will ensure sharing EurekaLog's code between EXE and DLL.

Important note:

Since your DLL will call EurekaLog from the EurekaLogCore package, the EurekaLogCore package will not know who is calling it (EXE or DLL). Therefore, it does not know where it should look for EurekaLog's options. That is why the EurekaLogCore package will always load EurekaLog's options (settings) from EXE. EurekaLog's settings from your DLL will be ignored.

This is kinda obvious, if you think about it: using the EurekaLogCore package means there is only one instance of EurekaLog in your process, so you can't have two EurekaLog's options (from EXE and DLL) at the same time.

In other words, configure EurekaLog in EXE. For DLL: you can configure EurekaLog as a "package" (if you don't call EurekaLog's code from your DLL) or as "Standalone DLL" (if you do call EurekaLog's code from your DLL).

"Application DLL"

If you are developing a Delphi DLL which will be used in your specific application only - then the solution is to configure your DLL as lightweight DLL.

Note: the solution from the "Delphi DLL" above will also work, but if you don't want to compile with packages (while you definitely should), using "Lightweight DLL" configuration is a possible alternative.

When you configure your DLL as a "Lightweight DLL": EurekaLog's code will not be included in your DLL. Instead: your DLL will make a calls to EurekaLog in your main EXE. Therefore, your process will have only one instance of EurekaLog (in your EXE), while your DLLs will call into EurekaLog from EXE.

Legacy applications

If you can't apply a real solution from above (for example, you are working on a legacy application and can't introduce changes) - contact our support to learn how to disable this check.

Conclusion

We understand that this error message could be frustrated for users which were using previous versions of EurekaLog. Especially considering the message does not appear at design-time, and it does not appear on startup at run-time, but it rather appears when a specific exception is thrown, which can be detected a lot later.

However, you should realize the error dialog is shown to clearly indicate an issue in your application rather than letting the application silently run further and produce hard to diagnose issues later.

We offer possible solutions, among simplest of which is reconfiguring EurekaLog in DLL as "Lightweigh DLL" - without touching your existing EXE/DLL code.

P.S. Read more about using EurekaLog in DLLs.
P.P.S. Read more about writing pure DLLs in Delphi.
P.P.P.S. We should note using a dedicated shared memory manager is a hack (crutch) from Delphi 2. New code should never use it. Using BPL packages (when developing a Delphi DLL) or following the "whoever allocates memory - frees it" rule (when developing a pure DLL) is a correct way.

Using EurekaLog with GMail (Google Mail) after May 1, 2025 and after May 14, 2025

2025-05-11T21:20:00.002+01:00

Google has announced that it’s disabling the less secure apps, third-party apps, or devices that ask you to sign in to your Google Account with your username and password on Google Workspace accounts from May 1st or May 14, 2025:

Starting March 14, 2025, you and your users must use OAuth with third-party apps to access Gmail, Google Calendar, and Google Contacts.You will no longer use a password for access (with the exception of app passwords). Google is turning off access to less secure apps—non-Google apps that can access Google Accounts with a username and password (basic authentication).

This is the same change that Google did in 2022 for most user accounts. But this time the same change is applied to Google Workspace accounts.

This change will affect you if you are using EurekaLog to send bug reports via GMail while using your GMail password. This method is considered unsecure and will no longer work on all Google accounts starting May 14, 2025.
This change will not affect you if you are using EurekaLog to send bug reports via GMail while using application-specific passwords.

While we’ve recommended using application-specific passwords instead of your GMail passwords for quite some time, but some customers have chosen to use the "Less Secure Apps" feature since it’s a little more straightforward.

In other words:

If you don't already have 2-Step Verification (also known as two-factor authentication) enabled for your account - you must turn it on. (Application-specific passwords can only be used with accounts that have 2-Step Verification turned on.) You can do it here: https://myaccount.google.com/security. Once enabled - you will have to confirm each sign in using your GMail password via a promt on already signed device, a physical security key, a code from a verification app, a phone call/SMS, or a backup code.
(Optional) Turn off/disable the "Less secure app access" feature.
You should create an application-specific password for your application with EurekaLog. You can do it here: https://myaccount.google.com/apppasswords. An App Password is a 16-digit (random) passcode that gives your app permission to access your Google Account.
Basically, you can use App Password instead of your (main/primary) GMail password. Most of the time, you’ll only have to enter an App Password once (per application), so don’t worry about memorizing it. You can always create a new/additional one.

Please note that we also recommend to use web-based bug tracker instead of e-mails for many reasons:

Using the large number's law and Exception Driven Development - EDD.
Using HTTP(S) typically avoids all pitfalls with firewalls and security.
Finer control over access rights.
Better UI and report management.
Etc...

P.S. There are two other alternative methods:

SMTP relay service
Restricted GMail SMTP server

Disable visual error dialogs for background apps

2025-01-27T19:01:00.009+00:00

Typically, background applications run as system services. In this case, fatal errors cause the application to close and possibly restart automatically if specified in the service's settings.

But sometimes, for some reason, you may want to make a background application as a regular user application. In this case, you would not want your application to show any error messages.

Test code

To test your application's behavior with fatal errors - you can use the following code:

// A thread function
function Crash(Arg: Pointer): Integer; stdcall;
begin
  // Artificially raise a test exception
  PInteger(nil)^ := 0;
  Result := 0; 
end;

function TForm1.Button1Click(Sender: TObject);
var
  TID: Cardinal;
begin
  // Create a new thread with the entry point specified above
  CloseHandle(CreateThread(nil, 0, @Crash, nil, 0, TID));
end;

This code creates a new Crash thread using the CreateThread system function. Threads created by the CreateThread function do not have any exception handlers, so if such a thread throws an exception and your thread's function code does not handle it, the exception is propagated to the system (a global handler), which results in a fatal exception.

In this case, our test code throws an EAccessViolation exception, trying to write an integer (0) to a null pointer (nil).

Apps with EurekaLog

If your project has EurekaLog on board, your application will behave differently, because EurekaLog will install its own global exception handler. It is much more difficult to get a fatal exception in a project with EurekaLog, so it is better to disable EurekaLog for testing.

Note that adding EurekaLog to your application does not guarantee that the dialog shown above will never appear for your application. EurekaLog runs from within the process. It means that there will always be a chance of a situation so bad that exception handlers inside the application cannot be called, which will lead to the process being closed from outside (by the system). For example:

// Calls a test exception
procedure Kaboom;
begin
  raise Exception.Create('Error Message');
end;

// Damages CPU stack and calls the Kaboom function
procedure Test; assembler;
asm
  // We simulate a "buffer overflow" bug
  mov [esp+4],  0;
  mov [esp+8],  0;
  mov [esp+12], 0;

  call Kaboom;
end;

// A test thread's function
function T(I: Integer): Integer; stdcall;
begin
  try
    Test;
  except
    // Does not matter
  end;
  Result := 0;
end;

This code will crash the application even with EurekaLog on board, since this code corrupts the system records of exception handlers. Therefore, when the Kaboom function raises a test exception, the system cannot call the exception handler (marked as "Does not matter" in the code example) and has no choice but to close the process.

Disabling system reports

So, to prevent your application from showing the "Program has stopped working" dialog, you can disable the WER (Windows Error Reporting) service for your application. You can do this by calling the following code when your application starts:

SetErrorMode(GetErrorMode or SEM_NOGPFAULTERRORBOX);

The SetErrorMode function specifies how the system or process should handle fatal errors. In particular, the SEM_NOGPFAULTERRORBOX flag specifies that the system should not generate Windows error reports.

Note that you must modify the already defined process mode, you cannot rewrite it completely from scratch, removing flags that you know nothing about. For example, the following code is WRONG:

SetErrorMode(SEM_NOGPFAULTERRORBOX);

If you need to turn off this mode, you should use a code like this:

SetErrorMode(GetErrorMode and (not SEM_NOGPFAULTERRORBOX));

Note that enabling this mode will completely disable the WER (Windows Error Reporting) service for your application.

Disabling only visual dialogs

If you do not want to completely disable WER for your application (for example, if you want to use the WER system logs to view the list of "crashes" of your application), you can disable only visual dialogs. This can be done by calling the following code:

var
  Flags: Cardinal;
begin
  if Failed(WerGetFlags(GetCurrentProcess, Flags)) then
    Flags := 0;
  WerSetFlags((Flags or WER_FAULT_REPORTING_NO_UI) and (not WER_FAULT_REPORTING_ALWAYS_SHOW_UI));

The WerSetFlags function sets the Windows Error Reporting (WER) options for the current process.

As with SetErrorMode, you should not call WerSetFlags blindly, overriding already set modes of operation, you should only change those modes that you want to change. Specifically, the code in the example above sets the WER_FAULT_REPORTING_NO_UI flag and clears the WER_FAULT_REPORTING_ALWAYS_SHOW_UI flag. The WER_FAULT_REPORTING_NO_UI flag tells WER to never show the error reporting user interface for this process. The flag WER_FAULT_REPORTING_ALWAYS_SHOW_UI, on the contrary, asks WER to always show the error reporting user interface for this process.

The WerSetFlags function, and the WER_FAULT_REPORTING_NO_UI, WER_FAULT_REPORTING_ALWAYS_SHOW_UI flags are not declared in the standard Delphi header files, but you can declare them yourself, import them from the JEDI Windows API Library or from EurekaLog. For example (for EurekaLog):

uses
  EWER;

var
  Flags: Cardinal;
begin
  // You should call this function before using anything from EWER unit
  InitWER; // imports WER functions
  
  // Will be False for very old Windows (like 2000 and XP)
  if Assigned(WerSetFlags) then
  begin
    if Failed(WerGetFlags(GetCurrentProcess, Flags)) then
      Flags := 0;
    WerSetFlags((Flags or WER_FAULT_REPORTING_NO_UI) and (not WER_FAULT_REPORTING_ALWAYS_SHOW_UI));
  end;

Disabling dialogs in EurekaLog

If EurekaLog is added to your project, it can also show dialogs about errors. You can disable these dialogs. First, of course, you should switch the main visual dialog to "None" in the project settings (disables the exception dialog).

If you have configured sending reports in your project, then you should disable visual support for sending reports by disabling the "Show send progress", "Show success message", and "Show failure message" options.

Finally, in some rare cases, EurekaLog can show simple messages (via MessageBox). These dialogs can also be disabled. To do this, you need to enable hooks for non-visual applications ("[Non-visual] Hides MessageBoxes") in the hooks settings. This option is enabled automatically if you select a suitable profile (for example, a system service) during the initial project setup for EurekaLog, but if you select the standard "VCL Forms application" profile, you need to enable this setting manually.

Important note: technically there is a callback in EurekaLog, which implements a MessageBox. Every time EurekaLog wants to show a simple message, this callback will be called. This callback can be set to show a visual dialog (like the usual MessageBox), it can be set to output to the concole, it can be set to do nothing. The "None" dialog sets the "[Non-visual] Hides MessageBoxes" setting, which sets the callback to do nothing. While the "MS Classic" dialog sets the callstack to show visual message box. Obviosly, you can't have both at the same time - you have either one or another.

Mixed mode apps or exceptions

Sometimes your application has to work in two modes:

Visual. For example, when launched by a user from the Start menu.
Non-visual. For example, when launched as a service or from autorun/Task Sheduler.

And sometimes your application wants to handle exceptions differently (even if it was visually launched by a user):

Show exception. For example, when an exception happens in the main (UI) thread.
Hide exception. For example, when an exception happens in a service background thread.

If this is the case - you would need to switch at run-time between being visual and hiding visuals.

First, you need to configure your application to be visual - set dialog to an appropriate option (such as "MS Classic"). Enable all other visual behaviour, like if your app would be run by a user.

Once you set up your application to behave correctly when interacting with a user - write some code to turn off visual behaviour at run-time. For example, if you write a mixed mode app, you can decice how it should run at startup. If it should run in the visual mode - do nothing. If it should run in non-visual mode - turn off visuals:

initialization
  if RunAsService then // your function to decide how to launch your app
  begin
    CurrentEurekaLogOptions.ExceptionDialogType := edtNone;
    CurrentEurekaLogOptions.sndSendInSeparatedThread := False;
    CurrentEurekaLogOptions.sndShowSendDialog := False;
    CurrentEurekaLogOptions.sndShowSuccessMsg := False;
    CurrentEurekaLogOptions.sndShowSuccessBugClosedOnlyMsg := False;
    CurrentEurekaLogOptions.sndShowFailureMsg := False;
    CurrentEurekaLogOptions.boSaveCompressedCopyInCaseOfError := False;
    CurrentEurekaLogOptions.boCopyLogInCaseOfError := False;
    CurrentEurekaLogOptions.sndScreenshot := ssNone;
  end;
end.

Please see: How to change EurekaLog's settings at run-time?

If you write an app, which handles various exceptions differently - then you have to decide which exceptions you want to hide. For example:

uses
  EEvents; // for RegisterEventExceptionNotify
 
// Custom handler to customize exception's handling 
procedure HideBackgroundExceptions(const ACustom: Pointer; 
  AExceptionInfo: TEurekaExceptionInfo; 
  var AHandle: Boolean; 
  var ACallNextHandler: Boolean);
begin
  // If the exception is coming from a background thread
  // (this is only an example, you can/should replace it with your own code)
  if AExceptionInfo.ThreadID <> MainThreadID then
  begin
    // Disable all visual feedback for this exception
    AExceptionInfo.Options.ExceptionDialogType := edtNone;
    AExceptionInfo.Options.sndShowSendDialog := False;
    AExceptionInfo.Options.sndShowSuccessMsg := False;
    AExceptionInfo.Options.sndShowSuccessBugClosedOnlyMsg := False;
    AExceptionInfo.Options.sndShowFailureMsg := False;
    AExceptionInfo.Options.boSaveCompressedCopyInCaseOfError := False;
    AExceptionInfo.Options.boCopyLogInCaseOfError := False;
    AExceptionInfo.Options.sndScreenshot := ssNone;
    AExceptionInfo.Options.sndSendInSeparatedThread := False;
  end;  
end;
 
initialization
  // Ask EurekaLog to call our code for each exception
  RegisterEventExceptionNotify(nil, HideBackgroundExceptions);
end.

P.S. If you are developing a service, you will probably want to use the system logging setup dialog instead of disabling the dialog completely.

P.P.S. Since you are writing a background application which runs as a standard user application, system restart settings will not be applied to your application. So it will be simply terminated in case of a crash. You may set up restart settings in EurekaLog, but you should be aware that these settings will only work if your application shut downs more or less gracefully (under control of EurekaLog). For example, we had a code example above that illustrates how EurekaLog-enabled application can perform a fatal crash. Your application will be closed by an external process (the system) in that case, so any user code from within your process won't be called (including EurekaLog). It means that if you want a reliable way to restart your application - you have to have some sort of external monitor process, which will restart your application in case of fatal crash.

See also:

Black Friday and Cyber Monday Sale

2024-11-28T20:39:00.003+00:00

Neos Eureka s.r.l. is proud to announce our Black Friday / Cyber Monday sale!

Use the following 30% off coupon code when checking out/paying to take advantage of this sale:

BFCM2024

This coupon code is valid from 29 November through 6 December 2024.

Existing customers should log in to their account at:
https://www.eurekalog.com/login.php
And select the license they wish to upgrade or extend. Enter the above code into the coupon code field at checkout time.

New customers can purchase licenses here:
https://www.eurekalog.com/buy.php
Enter the coupon code at checkout.

The coupon code is valid once per user account.

First, you need to select which option you want to purchase:

Second, you enter your billing details:

Don't forget to enter your Tax / VAT ID! And, of course, enter the discount coupon code.

Ensure the discount is applied and the tax looks correct. Finally, make a payment.

EurekaLog detects exceptions, memory leaks and other problems in your Delphi or C++ Builder application.

When trouble is found, it creates a bug report and sends it to your development team via Email or your web server. The bug report contains a stack trace that shows the place in your application where the crash occurred. The report can contain an optional screen shot, assembly code, configuration of the user's computer and many other factors.

If you have questions or comments then please contact us at:
https://www.eurekalog.com/support.php

The Secret of Access Denied

2024-03-07T18:44:00.006+00:00

A client contacted us and said that he could not install EurekaLog. More precisely: EurekaLog is installed, but subsequent launch of the IDE raises an error:

Can't load package C:\Program Files (x86)\Neos Eureka S.r.l\EurekaLog 7\Packages\Studio25\EurekaLogExpert250.bpl. Access is denied.

Moreover, the client claimed that the file exists, there is access to it, reinstalling EurekaLog does not help.

Additionally, it was found that the code from the EurekaLogExpert250.bpl package actually does not receive control (is not executed).

The IDE uses the same LoadPackage function from the SysUtils unit that you (your code) use. The IDE does not execute any secret code. The LoadPackage function is implemented as follows:

function LoadPackage(const Name: string; AValidatePackage: TValidatePackageProc): HMODULE;
begin
  Result := SafeLoadLibrary(Name);
  if Result = 0 then
    raise EPackageError.CreateResFmt(@sErrorLoadingPackage, [Name, SysErrorMessage(GetLastError)]); // -----
  try
    InitializePackage(Result, AValidatePackage);
  except
    FreeLibrary(Result);
    raise;
  end;
end;

where the InitializePackage function is implemented as:

procedure InitializePackage(Module: HMODULE; AValidatePackage: TValidatePackageProc);
type
  TPackageLoad = procedure;
var
  PackageLoad: TPackageLoad;
begin
  CheckForDuplicateUnits(Module, AValidatePackage);
  @PackageLoad := GetProcAddress(Module, 'Initialize'); //Do not localize
  if Assigned(PackageLoad) then
    PackageLoad
  else
    raise EPackageError.CreateFmt(sInvalidPackageFile, [GetModuleName(Module)]);
end;

As you can see: the only place where an exception with an error code from the OS (5 = ERROR_ACCESS_DENIED) can be raised when loading a package is the marked line. This means that an Access Denied error when loading a package can only occur if the call to the LoadLibrary function fails.

Therefore, the client was asked to create a new empty VCL application with the following test code:

procedure TForm1.Button1Click(Sender: TObject);
var
  Lib: HMODULE;
begin
  Lib := LoadPackage('C:\Program Files (x86)\Neos Eureka S.r.l\EurekaLog 7\Packages\Studio25\EurekaLogExpert250.bpl');
  if Lib = 0 then
    RaiseLastOSError
  else
    MessageBox(0, 'The package was loaded!', 'Test', 0);
end;

As it turns out, the test application loads the package successfully.

To be sure that the IDE was not executing any additional hidden code, we asked the client to create a new Design-Time package with a new unit containing only the test code:

unit Unit1;

procedure Register;

implementation

uses
  Windows, SysUtils;

procedure Register;
var
  Lib: HMODULE;
begin
  Lib := LoadPackage('C:\Program Files (x86)\Neos Eureka S.r.l\EurekaLog 7\Packages\Studio25\EurekaLogExpert250.bpl');
  if Lib = 0 then
    RaiseLastOSError
  else
    MessageBox(0, 'The package was loaded!', 'Test', 0);
end;

end.

And when the client tried to load this test package, the IDE again gave an error message.

Let's make an intermediate result:

The test application successfully loads the package;
The test package (and IDE) cannot load the package.

This strongly suggests that the problem is not with the package, but with the IDE itself.

We also tried the following:

Launch the IDE (without EurekaLog);

Open the Run / Load Process menu item;

Specify bds.exe as the target process for debugging;

Launch the second instance of the IDE. In this case: the first instance will be the debugger, and the second will be the debugged one;

In the process being debugged: try to add/load the EurekaLogExpert250.bpl package;

In the debugger: monitor for exceptions that occur.

This algorithm did not provide any new information. In the debugger: we saw that in the process being debugged, the LoadLibrary function returns 0, which leads to an error being raised - as we assumed above.

Since both we and the client had already checked the access rights to the file EurekaLogExpert250.bpl a hundred times and saw no problems, we had to do something else.

The EurekaLogExpert250.bpl package is a Design-Time package. It depends on the Run-Time package EurekaLogCore250.bpl. This means that if the LoadLibrary function loads the EurekaLogExpert250.bpl package, it will see that the EurekaLogExpert250.bpl package references the EurekaLogCore250.bpl file and will try to load it too. And if a problem arose while loading the EurekaLogCore250.bpl package, it will bubble up to the top level and will be returned to the caller by the LoadLibrary function.

Therefore, the client also checked the file EurekaLogCore250.bpl (located in the C:\Windows\System32 folder) and found no problems.

Next, we asked the client to use Microsoft/SysInternals Process Monitor tool to monitor how the IDE was accessing files. It was necessary to launch the IDE, open the adding component dialog, then launch the Process Monitor tool and specify the "Process Name=bds.exe => include" filter. Then try to add the package, see the error message and save the resulting report.

In the resulting report, we ran a search for the "Eureka" word and immediately saw that the bds.exe was able to open and read the EurekaLogExpert250.bpl file - which further confirms that there is nothing wrong with the EurekaLogExpert250.bpl file.

But the lines immediately below confused us: Process Monitor reported that the bds.exe is trying to access the EurekaLogCore250.bpl from IDE's \bin folder. This is strange because modern versions of EurekaLog do not touch IDE's \bin folder.

(Very) old versions of EurekaLog installed the ecc32.exe file in IDE's \bin folder. We had to remove this behavior because Modern versions of the IDE may throw an integrity/license verification error if there are third-party files in IDE's \bin folder:

Question: I’ve installed and registered C++ Builder or Delphi, yet when it starts I am brought to a web page with the error “Product or License Validation Error”. How can I fix this?
Answer: By far the most common cause for this error is having files or applications not provided by Embarcadero that are copied into the bin folder below where RAD Studio is installed. Only files provided by Embarcadero may reside in the bin folder.
Therefore, modern versions of EurekaLog do not copy any files to IDE's \bin folder.

But when we tried to check the access rights to the \bin\EurekaLogCore250.bpl file, we... did not find such file!

As it turns out: the \bin\EurekaLogCore250.bpl is, in fact, a directory! The mystery is solved!

So, the following happened:

The IDE calls the LoadPackage function to load the package;
The LoadPackage function calls the LoadLibrary function to load the EurekaLogExpert250.bpl file;
The LoadLibrary function (successfully) opens and reads the EurekaLogExpert250.bpl file;
The LoadLibrary function sees that the EurekaLogExpert250.bpl file contains a link/reference to the EurekaLogCore250.bpl file;
The LoadLibrary function tries to load the EurekaLogCore250.bpl file;
The LoadLibrary function uses standard operating system's library search rules and sees that EurekaLogCore250.bpl is located right here: in IDE's \bin folder;
The LoadLibrary function tries to load EurekaLogCore250.bpl from IDE's \bin folder;
The LoadLibrary function returns error 5 (Access Denied) because the EurekaLogCore250.bpl folder in IDE's \bin folder does not have the "EXECUTE" access right".

And, indeed, everything worked after deleting the EurekaLogCore250.bpl folder from IDE's \bin folder.

But where did the EurekaLogCore250.bpl folder in IDE's \bin folder came from? I don't know. The EurekaLog installer is made using InnoSetup. Of course, the InnoSetup installation file for EurekaLog has no idea about IDEs you have installed and folders in which they are installed. And therefore the InnoSetup installation file for EurekaLog will not be able to create any folder there - simply because it does not know where it is.

Registration of EurekaLog in the IDE is carried out by the standalone registration program: .exe file compiled in Delphi from our source code. The problem is that in our source code for EurekaLog registration does not have a single call to MkDir or ForceDirectories functions: the EurekaLog registration application does not create directories, it copies files and enters data about them into Windows registry.

Even if the EurekaLogCore250.bpl in IDE's \bin folder was created by our installer: why is it a directory and not a file? And why is it alone? Why are there no EurekaLogExpert250.bpl and EurekaLogComponent250.bpl - after all, these three files go together.

So far it looks like someone has created a EurekaLogCore250.bpl directory in IDE's \bin folder. Perhaps it was some kind of IDE expert?

If you are our client, if you saw this error and know who creates the EurekaLogCore250.bpl directory in IDE's \bin folder - please let us know.

P.S. Read more stories like this one or read feedback from our customers.

Beware of secondary exceptions

2023-12-07T17:14:00.002+00:00

We were contacted by a client who complained that EurekaLog was generating an error report in the wrong place. In fact, the client had an expected exception that he wanted to hide by showing a simple message instead. The client kindly showed his code:

try
  Query.Delete; // - an exception is raised here
except
  Query.Transaction.Rollback;
  ShowMessage('Sorry, could not delete the report');
  Exit;
end;

What's happening? Does EurekaLog really ignore user code?

If the client code were written like this:

try
  Query.Delete; // - an exception is raised here
except
  Exit;
end;

then there would be no problem: Query.Delete raises an exception, the exception is caught by the except block, which does nothing, and execution continues further, EurekaLog does not react (*).

However, the client code looks different: its except block does some (complex) exception recovery.

In any case, such exceptions are called handled because they are handled by the user's (client's) code. A handled exception is handled by cleanup code, which performs some recovery/rollback actions, after which program execution continues and the exception itself is removed.

In general, any cleanup code (be it a destructor or a rollback/recovery code) should be written in a such way so it will not raise exceptions. It seems to me that the logic here is obvious: if your normal code raises an exception, then you can always suggest a possible recovery actions (the so-called “Plan B”). For example, if an exception occurs when opening a document - then the document needs to be closed; If an exception occurs while accessing the printer - the print job must be canceled. If there is an error opening a file - you can try to open it again after a pause or user's action. And so on.

But what will you do if an error occurs in the “Plan B” itself? You wanted to cancel the print job, but it... is not cancelled. So what now? You will not be able to offer any reasonable recovery actions. Because you don't know what happened. Your variables may be corrupted. Hell, you might not even be able to allocate a block of memory right now! The only possible clean way is to kill/restart the application.

This is why the cleanup code must NOT raise exceptions. Because you can't do anything meaningful with these exceptions. In other words: the cleanup code must handle all exceptions that it knows how to handle.

But in practice, things may not be the same as in an ideal world.

In this case, the client's code raises a second exception inside Query.Transaction.Rollback. It means that the execution of the except block is interrupted and execution moves to the exception handler higher up the stack. It turns out that there are no more try blocks higher up the stack in the client's code, so execution is transferred to the global exception handler, which calls EurekaLog to generate a bug report.

Correcting the code will involve following the rule “cleanup code must not raise exceptions” (“cleanup code must handle known exceptions”). For example, as follows:

try
  Query.Delete; // - an exception is raised here
except
  try
    Query.Transaction.Rollback;
  except
    on EDatabaseError do; // - ignore database errors
  end;
  ShowMessage('Sorry, could not delete the report');
  Exit;
end;

In this case, the second exception will be handled in place and will not "bubble up" to the next exception handler (be it a try block or a global exception handler). It is important to write the correct code - i.e. so that it doesn't block exceptions that you don't know how to handle. For example, the following code is incorrect:

  try
    Query.Transaction.Rollback;
  except
    // - ignore ALL errors
  end;

It is incorrect because you do not know how to properly handle/rollback/recover from, for example, an EAccessViolation exception. It is best to write the code so that it takes into account the most narrow conditions for exceptions - only those that you know exactly how to handle. For example, if you know a specific type/code of the error when canceling a transaction - then write like this:

  try
    Query.Transaction.Rollback;
  except
    on E: ESomeSpecificDatabaseException do
      if E.ErrorCode = 1234 then
      begin
        // - ignore only this specific error
      end
      else
        raise;
  end;

Remarks:

(*) ...unless the Catch Handled Exceptions option is not enabled in EurekaLog. When the Catch Handled Exceptions option is enabled - EurekaLog will show bug reports about all exceptions, even if they were handled by except blocks. This option is intended for local debugging, as an aid in finding a "bad" code. It should not be used in production.
If you don't need to do special cleanup after an exception, but need to block an expected exception, then you can ignore it, or mark it as "expected".
If you do not fix your code so that your recovery/handling code does not raise exceptions, then you will have secondary exceptions. EurekaLog has a set of options that control EurekaLog's behavior for such exceptions.

Black Friday and Cyber Monday Sale

2023-11-17T08:59:00.001+00:00

We are pleased to announce Black Friday and Cyber Monday 30% discount on any of our EurekaLog products using the coupon code found below.

The sale starts on Black Friday (November, 24) and ends at the end of Cyber Monday (November, 27).

Enter this code when paying for the item on our web site:

BFCM2023

New customers (without existing licenses) can use the discount code here:

https://www.eurekalog.com/buy.php

EurekaLog 7.12 is out

2023-11-10T13:39:00.002+00:00

We are pleased to announce the availability of the new 7.12 version.

EurekaLog is a tool for Delphi and C++Builder that gives your application the power to catch every exception and memory/resource leak, generating a detailed log of the call stack (with unit, procedure and line number), optionally sending you a copy of each log entry via email or the Web via the most used Web Bug-Tracking tools (as Mantis, BugZilla, FogBugz, JIRA, YouTrack, Redmine, Exceptionless, GitLab, and GitHub).

EurekaLog represents the most advanced exception and memory leaks logger technology available for Delphi/C++Builder developers.

To learn more about EurekaLog, please visit our website at:
https://www.eurekalog.com

To download a demo, please visit:
https://www.eurekalog.com/downloads.php

If you would like to purchase a new license, please visit:
https://www.eurekalog.com/buy.php

Changes in 7.12 build:

Added: [IMPORTANT] Added workflow path from CLOSED to NEW/OPEN/REOPENED for some bug trackers. Please see
Added: [IMPORTANT] Added ability to catch non-exception crashes in C++ Builder, such as Abnormal Program Termination. Please see
Added: Support for RAD Studio 12
Added: Recompiled for RAD Studio 11 update 3
Added: New option for EurekaLog's behaviour when processing secondary exceptions during exception's processing
Added: Completely reworked internals of calling default RTL handler to allow proper feature functioning in all cases
Added: EurekaLog will now show call stack dump when EIP/RIP is invalid
Added: New variable: bug location (address); variable name: _Location
Added: "Reserve lower memory" option
Added: Support for mORMot2 debug info format
Added: Now user's address will be used as "Reply-to" header when sending bug reports
Added: --el_wait command line switch with default value of 60 seconds. Now EurekaLog will wait for executable file to become unlocked/writable (to workaround anti-viruses locking the compiled file)
Added: AddCustomDataToBugReport and AddCustomWebField functions (EEvents unit)
Added: "Largest Available Memory Block" value to bug reports
Fixed: BugZilla API was upgraded to a modern JSON API
Fixed: Possible rare range-check error
Fixed: Sending to Exceptionless fails with EVariantOverflowError on old IDEs
Fixed: Possible memory leaks when SMTP send fails
Fixed: Very rare memory errors for TEurekaExceptionInfo
Fixed: Various improvements for handling stack overflows, synchronize exceptions, multi-threaded call stacks
Fixed: Possible access violation when taking call stack of already shutdown thread
Fixed: Various multithreading issues
Fixed: [SMTP] name in the HELO command is now a fully qualified domain name
Fixed: Possible EurekaLog dialog hang when main window is not responding
Fixed: [x64] Debug info providers may fail to obtain information from modules loaded at high addresses (above 4 Gb)
Fixed: Rare hang in MS debug info provider startup
Fixed: Very rare memory leak
Fixed: Very rare range-check error
Fixed: EurekaLog may fail to read map file property (very rare)
Fixed: Empty network information in leak reports
Fixed: Old IDEs fail to decrypt passwords from options during leak reporting, leading to various issues
Fixed: Dialog, Log Builder and Send Engines classes will now expand exception-specific variables
Fixed: EurekaLog dialog may change DPI awareness of the thread
Fixed: [C++ Builder] TLS detection code could produce incorrect results in some cases; this leads to EurekaLog being disabled
Fixed: [Viewer] Possible Access Violation when there are unsaved changes
Fixed: [Viewer] Very rare range check error on opening some reports
Fixed: [Regression] Possible memory leak when both memory leaks and resource leaks are enabled
Fixed: [Obsolete] Rare Access Violation when using EAppMultiThreaded (e.g. "Auto-handle TThread exception" option is enabled)
Fixed: Various minor and internal improvements
Changed: Signature for OnPasswordRequest event

Creating an API (contract) for your own DLL

2023-09-06T22:26:00.008+01:00

Or: don't create your own DLLs without reading this article!

This article is not about EurekaLog, but about writing your own DLLs in general. This article is based on questions on the forums: "How do I return a string from a DLL?", "How do I pass and return an array of records?", "How do I pass a form to a DLL?".

So that you do not spend half your life figuring it out - in this article I will bring everything on a silver platter.

Important note: the article must be read sequentially. Code examples are given only as examples: the code of examples is added with new details at each step of the article. For example, at the very beginning of the article there is no error handling, "classic" methods are used (such as using GetLastError, the sdtcall convention, etc.), which are replaced by more adequate ones in the course of the article. This is done for the reason that "new" ("unusual") designs do not raise questions. Otherwise, with each example, one would have to insert a note like: "this is discussed in that paragraph below, but that - in this one here." In any case, at the end of the article there is a link to the sample code written by taking into account everything said in the article. You can just grab it and use it. And the article explains why it is created the way it is. If you are not interested in "why" - scroll to the end to the conclusion and find a link to download the example.

Content

General Concepts
Data Types
String Data and Encodings
- ANSI and Unicode
Shared Memory Manager (and why you shouldn't use it)
API Memory Management
Error Handling (and calling convention)
DllMain Workaround
Callback Functions
Other Rules
Conclusion (and code examples)

General Concepts

When you develop your own DLL, you must come up with the prototypes of the functions exported from it (i.e. "headers"), as well as the contract based on them (i.e. calling rules). Together, this forms your DLL's API. API or Application Programming Interface (Application Programming Interface) is a description of the ways in which one code can interact with another. In other words, API is a tool for application integration.

When you develop your DLL, you must determine under what conditions it will be used:

Can it be used by applications written in another programming language (for example, Microsoft Visual C++) - "pure DLL" ("universal DLL", "generic DLL");
Or the DLL can only be used by applications written in the same language, "Delphi DLL".

This is a fundamental point that you should decide first of all: even before you start writing code and even designing the API of your DLL. The fact is that you can use all the features of your programming language when creating an API in the second case ("Delphi DLL"). For example, for Delphi this means the ability to use strings, objects (in particular, forms, components), dynamic arrays, specialized simple types (Extended, sets, etc.) - in general, all that does not exist in other languages. It also means the ability to share memory, do transparent error handling (cross-module exceptions).

If you go this route, then you should consider using run-time packages (BPLs) instead of DLLs. BPL packages are specialized DLLs that are specifically tailored for use only in Delphi, which gives you a lot of goodies. But more on that later.

On the other hand, if you're developing a "pure DLL" then you can't use features in your language that don't exist in other programming languages. And in this case, you can only use "well-known" data types. But more on that below.

This article is mainly about "pure DLLs" in Windows.

What you will need to create when developing your DLL API:

Headers, header files - a set of source files that contain declarations of structures and functions used in the API. As a rule, they do not contain implementations. Header files are provided in several languages - as a rule, this is the language in which the program is written (in our case, Delphi), C++ (as a standard) and some additional ones (Basic, etc.). All of these files are equivalent and are simply a translation from one programming language to another. The more languages included, the better. If you do not provide header files for a particular language, programmers in that language will not be able to use your DLL unless they themselves translate the files from the provided language (Delphi or C++) into their language. Therefore, the absence of headings in some language is not a red "stop", but a sufficient obstacle.
Documentation - is a verbal description of the API and it should specify additional rules not included in the header syntax. For example, the "specific function can be called by passing a number to it" fact is an information from the headers. And "before calling this function you need to call another function" fact is an information from the documentation. Such documentation should at least contain a formal description of the API - a listing of all functions, methods, interfaces and data types with explanations of "how" and "why" (the so-called Reference). Additionally, the documentation may contain an informal description of the process of using the DLL (guide, how-to, etc.). In the simplest cases, documentation is written directly in headers (comments), but most often it is a standalone file (or files) in chm, html or pdf format.

SDK (Software Development Kit) - a set of headers + documentation. The SDK is what a third party developer needs to use your DLL. An SDK is something you must create and publicly distribute to anyone who wants to use your DLL.

Data Types

If you want a "pure DLL", then you can't use Delphi-specific data types in your API because they don't have a counterpart in other languages. For example, string, array of, TObject, TForm (and in general - any objects, and even more so components) and so on.

What can be used? Integer types (Integer, Cardinal, Int64, UInt64, NativeInt, NativeUInt, Byte, Word etc., I wouldn't recommend using Currency unless you really need it), real types (Single and Double; I would recommend avoiding the Extended and Comp types unless you really need them), TDateTime (it is alias for system's OLEDate), enumerated and subrange types (with some caveats), character types (AnsiChar and WideChar - but not the Char), strings (only as WideString/BSTR), boolean (BOOL, but not the Boolean), interfaces (interface) whose methods use valid types, records (record) from the above types, and pointers to them (including pointers to arrays of the above types, but not dynamic arrays). Arrays are usually passed as two parameters: a pointer to the first element of the array and the number of elements in the array.

How do you know which type can be used and which can't? A relatively simple rule - if you don't see a type in this list, and the type is not in the Windows unit (Winapi.Windows unit since Delphi XE2), then that type cannot be used. If the type is listed above or it is in the Windows/Winapi.Windows unit, use it. This is a rather rough rule, but it will do for a start.

In case of using records (record) - you need to specify data alignment. Use either the packed keyword (no alignment) or the {$A8} directive (8-byte alignment) at the beginning of the header file.

In case of using enumerated types (Color = (clRed, clBlue, clBlack);) - add the {$MINENUMSIZE 4} directive to the beginning of the headers (the size of the enumerated type is at least 4 bytes ).

String Data and Encodings

If you need to pass strings to the DLL or return strings from the DLL - use only the BSTR type. Why?

The BSTR type available in all programming languages.
Note: For historical reasons, the BSTR type is called WideString in Delphi. Therefore, to make the contents of your Delphi headers more understandable to developers in other languages, add the following code to their beginning:
```
type
   BSTR = WideString;
```
and then use the BSTR everywhere in API/headers.
The BSTR (WideString) type is one of Delphi's automagic types, i.e. you don't have to manually allocate and deallocate memory. The compiler will automatically do everything for you;
The BSTR type has a fixed encoding: Unicode. Therefore you won't have problems with a wrong code page;
Delphi compiler magic allows you to simply assign BSTR (via the assignment operator :=) to any Delphi string and vice versa. All necessary conversions will be done automatically under the hood of the language, no conversion functions need to be called;
Memory for BSTR strings is always allocated through the same memory manager so you will never have problems transferring memory between executable modules (see below);

If for some reason you can't use the BSTR type then use PWideChar:

Don't use PAnsiChar because it's 2023, not 1995. Using PAnsiChar gives you a lot of encoding headaches;
Do not use PChar because it is not uniquely defined: it can be either PAnsiChar or PWideChar (depending on compiler version).

Similar to using the system's BSTR name instead of the Delphi's WideString name: you can also do this for the PWideChar type:

type
   LPWSTR = PWideChar;

and then use LPWSTR. The LPWSTR is the name of the system data type, which is called PWideChar in Delphi.

Of course, you get a bunch of cons when using LPWSTR/PWideChar instead of WideString:

You need to manually allocate and deallocate memory for PWideChar, which increases the chances of memory leak problems;
While in some cases you can make direct assignments (e.g. PWideChar to a string), more often you can't. You will have to call conversion functions and/or memory allocation/copy functions;
Memory for PWideChar strings is allocated as usual (without a dedicated memory manager), i.e. you have a problem with passing memory across a module boundary (see below);
PWideChar has no field for length. So if you want to pass strings with #0 inside and/or you want to pass large strings, then you have to explicitly pass the length of the string along with the string (two parameters instead of one).

ANSI and Unicode

From the above, it directly follows that all your exported functions must be in Unicode. Do not just look at the Windows API to make two versions of functions (with -A and -W suffixes) - just make one version (no suffix, just Unicode). Yes, do that even if you are developing on the ANSI version of Delphi (like Delphi 7): you don't need to make ANSI versions of the exported functions. It's not 1995 now.

Shared Memory Manager

(and why you shouldn't use it)

In programming languages, dynamic memory is allocated and deallocated by a special code in the program - the so-called memory manager. For example, the memory manager implements functions like GetMem and FreeMem in Delphi. All other memory management methods (New, SetLength, TForm.Create, etc.) are just adapters (i.e. somewhere internally they call GetMem and FreeMem).

The problem is that each executable module (be it a DLL or an exe) has its own memory manager code, and, for example, the Delphi memory manager does not know anything about the Microsoft C++ memory manager (and vice versa). Therefore, if you allocate memory in Delphi and, for example, try to transfer it to Visual C++ code, then nothing good will happen. Moreover, even if you allocate memory in Delphi DLL and return it to Delphi exe, things will be even worse: both executable modules use two different, but same type memory managers. The exe memory manager will look at the memory and it will seem to him that this is his memory (after all, it is allocated by a similar memory manager), he will try to free it, but only damage the accounting data.

The solution to this problem is simple - you need to use the rule: whoever allocates memory, frees it.

This rule can be enforced in a number of ways. Often mentioned method: using the so-called shared memory manager. The essence of the method is that several modules "agree" to use the same memory manager.

When you create a DLL, you are told about this feature by a comment at the beginning of the .dpr file of the DLL:

{ Important note about DLL memory management: ShareMem must be the
   first unit in your library's USES clause AND your project's (select
   Project-View Source) USES clause if your DLL exports any procedures or
   functions that pass strings as parameters or function results. This
   applies to all strings passed to and from your DLL--even those that
   are nested in records and classes. ShareMem is the interface unit to
   the BORLNDMM.DLL shared memory manager, which must be deployed along
   with your DLL. To avoid using BORLNDMM.DLL, pass string information
   using PChar or ShortString parameters. }

This is a monstrously wrong comment:

The comment talks about the need to use a shared memory manager as if it is the only way to solve the memory sharing problem - which is fundamentally wrong (see below);
The comment only talks about strings, although the problem described applies to any data with dynamic memory allocation: objects, dynamic arrays, pointers;
The comment does not mention in any way what to do with non-string data;
Using a shared memory manager does not correlate in any way with using a standalone DLL. This is just one of the possible implementations;
The comment requires the use of the PChar type to avoid the described problem - which is also wrong (see our discussion above about encodings);
The comment requires the use of the ShortString - which, again, is wrong from a "pure DLL" point of view (ShortString is a Delphi-specific type). Although, this is already a nitpick, since the use of Delphi strings and Delphi DLL as a common memory manager already puts an end to the "universal DLL" concept.

Unfortunately, this comment "from the creators of Delphi" has spawned a huge amount of myths and bad practices.

What's wrong with using a shared memory manager?

Other programming languages know nothing about Delphi's memory manager;
And since you're targeting only Delphi, why do you need a DLL? Build the program with run-time packages (BPL) - this will automatically give you:
- Shared memory manager in rtl.bpl;
- Guaranteeing the compatibility of the structure of objects, since all modules will be assembled by one compiler;
- No duplication of RTL and VCL (errors like "TForm is not compatible with TForm", two Application objects, etc.);
- Easy error handling with exceptions.
The shared memory manager makes it very difficult to find memory leaks, because a module can load, allocate memory, unload, and the created leak will only be found during the finalization of the memory manager when the program exits.

To summarize: a shared memory manager is a crutch. You don't have to use it. What should be used? See sections below.

API Memory Management

So how do you transfer memory from the DLL to the caller and vice versa? There are several ways.

Incorrect Way

First, what not to do.

First, don't "do it like Delphi": don't use a shared memory manager - for the reasons mentioned above.

Secondly, don't "do it like Windows": many look at the Windows API and do the same. But they miss the fact that this API was created in 1995, and many functions come from even earlier: 16-bit Windows. Those environments and conditions for which these functions were created no longer exist today. Today there are much simpler and more convenient ways.

For example, here is a typical Windows function:

function GetUserName(lpBuffer: PWideChar; var nSize: DWORD): BOOL; stdcall;

Parameters
lpBuffer
A pointer to the buffer to receive the user's logon name. If this buffer is not large enough to contain the entire user name, the function fails.

pcbBuffer
On input, this variable specifies the size of the lpBuffer buffer, in TCHARs. On output, the variable receives the number of TCHARs copied to the buffer, including the terminating null character.

If lpBuffer is too small, the function fails and GetLastError returns ERROR_INSUFFICIENT_BUFFER. This parameter receives the required buffer size, including the terminating null character.

To get a result from such a Windows function, it must be called twice. First you call the function to determine the size of the buffer, then you allocate the buffer, and only then you call the function again. But what if the data changes during this time? Function may run out of space again (on the second call). Thus, to reliably get the complete data, you have to write a loop. This is horror. Don't do that.

Strings

Strings are easy - just use the BSTR (which is WideString). We have discussed this above in details.

Note that in some cases you can return complex structured data (objects) as JSON or a similar way of packing the data into a string. And if this is your case - you can also use the BSTR type.

In all other cases, you need to use one of the three methods below.

System Memory Manager

You can fulfill the "who allocates memory - releases it" rule as follows: ask a third party to allocate and release memory, which both the called and the caller know about. For example, such a third party could be any system memory manager. This is exactly how BSTR/WideString works. Here are some options you can use:

Process system heap:
- The HeapAlloc and HeapFree called for the GetProcessHeap;
- The GlobalAlloc and GlobalFree;
- The LocalAlloc and LocalFree.
All of these functions allocate memory from the same process dynamic heap. Several variants appeared for historical reasons.
COM-like memory managers:
- The CoTaskMemAlloc and CoTaskMemFree;
- The SHAlloc and SHFree;
And again: all these functions are equivalent today. Several feature options appeared for historical reasons.
The VirtualAlloc and VirtualFree.

Note: COM memory manager and Shell functions can be called immediately, without COM/OLE initialization.

Pretty big list. Which one is better to use?

The VirtualAlloc/VirtualFree allocate memory with a granularity of 64Kb, so you should only use them if you need to exchange huge data;
GlobalAlloc/GlobalFree and LocalAlloc/LocalFree are pretty much outdated and have more overhead than HeapAlloc/HeapFree, so you don't need to use them;

That leaves us with the HeapAlloc/HeapFree and COM. The Heap option may very well be the default. COM memory managers may be more familiar to some programming languages. In addition, there is a ready-made memory manager interface (see below). In general, it is more like taste choice, not much real difference.

Here is an example of how it might look in code. In DLL (simplified code without error handling):

uses
  ActiveX; // or uses OLE2;

function GetDynData(const AFlags: DWORD; out AData: Pointer; out ADataSize: DWORD): BOOL; stdcall;
var
  P: array of Something;
begin
  P := { ... prepare data to return ... };

  ADataSize := Length(P) * SizeOf(Something);
  AData := CoTaskMemAlloc(ADataSize);
  Move(Pointer(P)^, AData^, ADataSize);

  Result := True;
end;

exe:

uses
  ActiveX; // or uses OLE2;

var
  P: array of Something;  
  Data: Pointer;
  DataSize: DWORD;
begin
  GetDynData(0, Data, DataSize);

  SetLength(P, DataSize div SizeOf(Something));
  Move(Data^, Pointer(P)^, DataSize);
  CoTaskMemFree(Data);
  
  // Work with P
end;

Note: it is just an example. In real applications, you can (on the callee side) both prepare data immediately in the returned buffer (provided that you know its size in advance), and (on the caller side) work with the returned data directly, without copying it to another type of buffer.

Of course, at the same time, your SDK should have documentation on the GetDynData function, which will explicitly say that the returned memory must be freed by calling CoTaskMemFree, like this:

GetDynData

Returns XYZ.

Syntax

function GetDynData(

const AFlags: DWORD;

out AData: Pointer;

out ADataSize: DWORD

): BOOL; stdcall;

Parameters

AFlags [in, optional]

Type: DWORD

Optional flags: ...

AData [out]

Type: Pointer

Pointer to a data of the ADataSize bytes. The caller should free this data by calling the CoTaskMemFree function.

ADataSize [out]

Type: DWORD

Size of the AData in bytes.

Returns

If the function succeeds - it returns True.
If the function fails - it returns False. You can call the GetLastError function to learn the failure reason.

Remarks

...

Examples

A usage example can be found in the Getting the data sample example code.

Requirements

API version

1

Headers

MyDll.pas

Note: of course, the CoTaskMemAlloc/CoTaskMemFree calls can be replaced with HeapAlloc/HeapFree or any other option convenient for you.

Note that with this method, you typically need to copy the data twice: in the callee (to copy the data from the prepared location to a location suitable for return to the caller) and possibly in the caller (to copy the returned data into structures suitable for further use). Sometimes you can get away with a single copy if the caller can use the data right away. But it is rare to get rid of copying data in the callee.

Dedicated Wrapper Functions

Another option is to wrap your preferred memory manager in an exportable function. Accordingly, the documentation for the function should indicate that to free the returned memory, you need to call not CoTaskMemFree (or whatever you used there), but your wrapper function. Then you can simply return prepared data immediately, without copying. For example, in a DLL (simplified code without error handling):

function GetDynData(const AFlags: DWORD; out AData: Pointer; out ADataSize: DWORD): BOOL; stdcall;
var
  P: array of Something;
begin
  P := { ... prepare your data ... };

  ADataSize := Length(P) * SizeOf(Something);
  Pointer(AData) := Pointer(P); // copy the pointer, not the data itself
  Pointer(P) := nil; // block the auto-release

  Result := True;
end;

procedure DynDataFree(var AData: Pointer); stdcall;
var
  P: array of Something;
begin
  if AData = nil then
    Exit;

  Pointer(P) := Pointer(AData); // and again: copy just the pointer
  AData := nil; 

  Finalize(P); // a matching release function
  // (it is optional in this particular case)
end;

exe:

var
  P: array of Something;  
  Data: Pointer;
  DataSize: DWORD;
begin
  GetDynData(0, Data, DataSize);

  SetLength(P, DataSize div SizeOf(Something));
  Move(Data^, Pointer(P)^, DataSize);
  DynDataFree(Data);
  
  // Work with P
end;

Note: we can't just copy the pointer to the array on the caller's side because the GetDynData contract says nothing about the compatibility of the returned data with Delphi's dynamic array. Indeed, a DLL can be written in MS Visual C++, which does not have dynamic arrays.

As in the previous case, this contract must also be explicitly stated in your SDK's documentation:

AData [out]

Type: Pointer

Pointer to a data of the ADataSize bytes. The caller should free this data by calling the DynDataFree function.

Note that by using a wrapper function you can reduce the amount of data copying, because now you don't need to copy the data on the caller's side, because you use the same memory manager for both calculations and for returning the data. The disadvantage of this method is the need to write additional wrapper functions. Sometimes you can get away with one generic wrapper function common to all exported functions. But more often than not, you will need an individual cleanup function for each exported function (returning data) if you want to use "just one copy" advantage.

If you use one generic cleanup function, you can return it as the IMalloc interface. This will be more familiar to those familiar with the basics of COM. But it will also allow you not only to return memory to the caller, but also to accept memory from the caller with transfer of ownership. For example:

uses
  ActiveX; // or Ole2

type
  TAllocator = class(TInterfacedObject, IMalloc)
    function Alloc(cb: Longint): Pointer; stdcall;
    function Realloc(pv: Pointer; cb: Longint): Pointer; stdcall;
    procedure Free(pv: Pointer); stdcall;
    function GetSize(pv: Pointer): Longint; stdcall;
    function DidAlloc(pv: Pointer): Integer; stdcall;
    procedure HeapMinimize; stdcall;
  end;

{ TAllocator }

function TAllocator.Alloc(cb: Integer): Pointer;
begin
  Result := AllocMem(cb);
end;

function TAllocator.Realloc(pv: Pointer; cb: Integer): Pointer;
begin
  ReallocMem(pv, cb);
  Result := pv;
end;

procedure TAllocator.Free(pv: Pointer);
begin
  FreeMem(pv);
end;

function TAllocator.DidAlloc(pv: Pointer): Integer;
begin
  Result := -1;
end;

function TAllocator.GetSize(pv: Pointer): Longint;
begin
  Result := -1;
end;

procedure TAllocator.HeapMinimize;
begin
  // does nothing
end;

function GetMalloc(out AAllocator: IMalloc): BOOL; stdcall;
begin
  AAllocator := TAllocator.Create;
  Result := True;
end;

//_______________________________________

function GetDynData(const AOptions: Pointer; out AData: Pointer; out ADataSize: DWORD): BOOL; stdcall;
var
  P: array of Something;
begin
  P := { ... prepare the data with AOptions ... };
  // Assume the AOptions was passed with ownership
  FreeMem(AOptions); 

  ADataSize := Length(P) * SizeOf(Something);
  AData := GetMem(ADataSize);
  Move(Pointer(P)^, Pointer(AData)^, ADataSize);

  Result := True;
end;

exe:

var
  A: IMalloc;
  Options: Pointer;
  P: array of Something;
  Data: Pointer;
  DataSize: DWORD;
begin
  GetMalloc(A);

  Options := A.Alloc({ options' size });
  { Preparing Options }
  GetDynData(Options, Data, DataSize);
  // Do not free Options, because we have passed ownership to the GetDynData

  SetLength(P, DataSize div SizeOf(Something));
  Move(Data^, Pointer(P)^, DataSize);
  A.Free(Data);

  // Work with P
end;

Note: of course, it is a bit of a nonsensical example, because in this particular case there is no need to pass the ownership of the AOptions to the GetDynData function: the caller can clean up the memory himself, then the callee will not need to free the memory. But it is just an example. In real applications, you may need to keep AOptions inside the DLL for longer than the function's call. The example shows how this can be done by hiding the memory manager behind a facade.

Also note that if you implement the TAllocator.GetSize method, then the ADataSize parameter can be removed.

Interfaces

Instead of using the system memory manager and/or special export functions (two ways above), it is much more convenient to use interfaces for the following reasons:

An interface is a record with function pointers, an analogue of a class with virtual functions. Due to this, each method automatically becomes a wrapper function from the previous paragraph, i.e. always works with the right memory manager. In other words, there is no need to use a fixed third-party memory manager, nor to introduce wrapper functions;
Any programming languages can understand interfaces;
Interfaces can pass complex data (objects);
Interfaces are self-cleanup types (in Delphi), no need to explicitly call cleanup functions;
Interfaces can be easily modified by extending them in future versions of your DLL;
The way Delphi implements interfaces using compiler magic makes it easy to implement proper error handling (see the next section below).

The previous example can be implemented with interfaces like this:

type
  IData = interface
  ['{C79E39D8-267C-4726-98BF-FF4E93AE1D44}']
    function GetData: Pointer; stdcall;
    function GetDataSize: DWORD; stdcall;

    property Data: Pointer read GetData; 
    property DataSize: DWORD read GetDataSize; 
  end;

  TData = class(TInterfacedObject, IData) 
  private
    FData: Pointer;
    FDataSize: DWORD;
  protected
    function GetData: Pointer; stdcall;
    function GetDataSize: DWORD; stdcall;
  public
    constructor Create(const AData: Pointer; const ADataSize: DWORD);
  end;

constructor TData.Create(const AData: Pointer; const ADataSize: DWORD);
begin
  inherited Create;
  if ADataSize > 0 then
  begin
    GetMem(FData, ADataSize);
    Move(AData^, FData^, ADataSize);
  end;
end;

function TData.GetData: Pointer; stdcall;
begin
  Result := FData;
end;

function TData.GetDataSize: DWORD; stdcall;
begin
  Result := FDataSize;
end;

//________________________________

function GetDynData(const AFlags: DWORD; out AData: IData): BOOL; stdcall;
var
  P: array of Something;
begin
  P := { ... preparing the data ... };

  AData := TData.Create(Pointer(P), Length(P) * SizeOf(Something)); 

  Result := True;
end;

exe:

var
  P: array of Something;  
  Data: IData;
begin
  GetDynData(0, Data);

  SetLength(P, Data.DataSize div SizeOf(Something));
  Move(Data^, Data.Data^, Data.DataSize);
  
  // Work with P
end;

In this case, we have made one universal IData interface that can be written once and be used in all functions. Although it does not require writing special code for every function, it also results in data copying on the side of the callee, as well as lack of typing. Here's what an improved DLL might look like:

type
  IData = interface
  ['{C79E39D8-267C-4726-98BF-FF4E93AE1D44}']
    function GetData: Pointer; stdcall;
    function GetDataSize: DWORD; stdcall;

    property Data: Pointer read GetData; 
    property DataSize: DWORD read GetDataSize; 
  end;

  TSomethingArray = array of Something;

  TSomethingData = class(TInterfacedObject, IData) 
  private
    FData: TSomethingArray;
    FDataSize: DWORD;
  protected
    function GetData: Pointer; stdcall;
    function GetDataSize: DWORD; stdcall;
  public
    constructor Create(var AData: TSomethingArray);
  end;

constructor TSomethingData.Create(var AData: TSomethingArray);
begin
  inherited Create;
  FDataSize := Length(AData) * SizeOf(Something);
  if FDataSize > 0 then
  begin
    Pointer(FData) := Pointer(AData);
    Pointer(AData) := nil;
  end;
end;

function TSomethingData.GetData: Pointer; stdcall;
begin
  Result := Pointer(FData);
end;

function TSomethingData.GetDataSize: DWORD; stdcall;
begin
  Result := FDataSize;
end;

function GetDynData(const AFlags: DWORD; out AData: IData): BOOL; stdcall;
var
  P: TSomethingArray;
begin
  P := { ... preparing the data ... };

  AData := TSomethingData.Create(P); 

  Result := True;
end;

In this case, the outer wrapper (that is, the interface) remains unchanged, only the DLL code changes. So the caller's code (in the exe) doesn't change either. But if you change the contract (interface), then you can do the following:

type
  ISomethingData = interface
  ['{CF8DF791-1E8D-4363-94A2-9FF035A9015A}']
    function GetData: Pointer; stdcall;
    function GetDataSize: DWORD; stdcall;
    function GetCount: Integer; stdcall;
    function GetItem(const AIndex: Integer): Something; stdcall;

    property Data: Pointer read GetData; 
    property DataSize: DWORD read GetDataSize; 
    property Count: Integer read GetCount;
    property Items[const AIndex: Integer]: Something read GetItem; default; 
  end;

  TSomethingArray = array of Something;

  TSomethingData = class(TInterfacedObject, ISomethingData) 
  private
    FData: TSomethingArray;
    FDataSize: DWORD;
  protected
    function GetData: Pointer; stdcall;
    function GetDataSize: DWORD; stdcall;
    function GetCount: Integer; stdcall;
    function GetItem(const AIndex: Integer): Something; stdcall;
  public
    constructor Create(var AData: TSomethingArray);
  end;

constructor TSomethingData.Create(var AData: TSomethingArray);
begin
  inherited Create;
  FDataSize := Length(AData) * SizeOf(Something);
  if FDataSize > 0 then
  begin
    Pointer(FData) := Pointer(AData);
    Pointer(AData) := nil;
  end;
end;

function TSomethingData.GetData: Pointer; stdcall;
begin
  Result := Pointer(FData);
end;

function TSomethingData.GetDataSize: DWORD; stdcall;
begin
  Result := FDataSize;
end;

function TSomethingData.GetCount: Integer; stdcall; 
begin
  Result := Length(FData);
end;

function TSomethingData.GetItem(const AIndex: Integer): Something; stdcall;
begin
  Result := FData[AIndex];
end;

function GetDynData(const AFlags: DWORD; out AData: ISomethingData): BOOL; stdcall;
var
  P: TSomethingArray;
begin
  P := { ... preparing the data ... };

  AData := TSomethingData.Create(P); 

  Result := True;
end;

and then the caller turns into this:

var
  Data: ISomethingData;
begin
  GetDynData(0, Data);

  // No need to copy, just work with Data:
  for X := 0 to Data.Count do
    AddToList(Data[X]);
end;

In general, there are quite wide possibilities, you can do almost anything you want. And even if you first made a contract through IData, then later you can add ISomethingData by simply extending the interface with inheritance. However, older clients of your version 1 DLL will use IData, while version 2 clients may request the more convenient ISomethingData.

As you can see from the code above, interfaces are more useful the more complex the returned data. It is very easy to return complex objects as interfaces, while returning a simple block of memory means writing a lot of code.

The obvious downside is the need to write more code for interfaces, since you need a thunk object to implement the interface. But this minus is easily neutralized by the next paragraph (see "Error Handling" below). It's also partially removed if you originally need to return an object (because it doesn't require a thunk object, the returned object itself can implement the interface).

Note: the code above is just an example. In real code, you need to add error handling and move the IData/ISomethingData interface definitions to separate files (your SDK headers).

Error Handling

(and calling convention)

When a programmer writes code, he determines the sequence of actions in the program, placing operators, function calls, and so on in the right order. At the same time, the implemented sequence of actions corresponds to the logic of the algorithm: first we do this, then this, and finally this. The main code corresponds to the "ideal" situation, when all files are in their places, all variables have valid values, and so on. But during the actual operation of the program, situations inevitably occur when the code written by the programmer will operate in an unacceptable (and sometimes unforeseen) environment. Such (and some other) situations are called by the generalized word "error". Therefore, the programmer must somehow determine what he will do in such situations. How will he determine the admissibility of the situation, how to react to it, etc.

As a rule, the minimum blocks subject to control are a function or procedure (subroutine). Each subroutine performs a specific task. And we can expect a different level of "success" for this task: the task was successful or an error occurred during its execution. To write reliable code, we absolutely need a way to detect error situations - how do we determine that an error has occurred in a function? And responding to them is the so-called "error recovery" (i.e.: what will we do when an error occurs?). Traditionally, there are two main ways to handle errors: error codes and exceptions.

Error codes

(and why not to use them)

Error codes are perhaps the easiest way to respond to errors. Its essence is simple: the subroutine must return some sign of the success of the task. There are two options here: either it will return a simple sign (success/failure), or it will return the execution status (in other words - "error description"), i.e. a certain code (number) of one of several predefined situations: the function parameters are incorrectly set, the file is not found, etc. In the first case, there may be an additional function that returns the execution status of the last function called. With this approach, errors found in the function are usually passed up (to the calling function). Each function must check the results of other function calls for errors and perform appropriate processing. Most often, the processing is simply passing the error code even higher, to the "higher" calling function. For example: function A calls B, B calls C, C detects an error and returns an error code to B. B checks the return code, sees that an error occurred, and returns an error code to A. A checks the return code and issues an error message (or decides to do something else).

For example, here is a typical Windows API function:

RegisterClassEx

Registers a window class for subsequent use in calls to the CreateWindow or CreateWindowEx function.

Syntax

function RegisterClassEx(

const AClass: TWndClassEx

): ATOM; stdcall;

Parameters

AClass [in]

Type: TWndClassEx

A pointer to a WNDCLASSEX structure. You must fill the structure with the appropriate class attributes before passing it to the function.

Returns

If the function succeeds, the return value is a class atom that uniquely identifies the class being registered. This atom can only be used by the CreateWindow, CreateWindowEx, GetClassInfo, GetClassInfoEx, FindWindow, FindWindowEx, and UnregisterClass functions and the IActiveIMMap.FilterClientWindows method.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

... cut ...

Examples

For an example, see Using Window Classes.

Requirements

Minimum supported client

Windows 95

Headers

Winuser.h

Library

User32.dll

It is a typical way to handle errors in the classic Windows API. In this case: the so-called Win32 error codes. The Win32 error code is a usual DWORD number. Error codes are fixed and declared in the Windows unit. The absence of an error is taken as ERROR_SUCCESS or NO_ERROR (equal to 0). Constants are defined for all possible errors. Those begin (usually) with the ERROR_ word, for example:

  { Incorrect function. }
  ERROR_INVALID_FUNCTION = 1;   { dderror }

  { The system cannot find the file specified. }
  ERROR_FILE_NOT_FOUND = 2;

  { The system cannot find the path specified. }
  ERROR_PATH_NOT_FOUND = 3;

  { The system cannot open the file. }
  ERROR_TOO_MANY_OPEN_FILES = 4;

  { Access is denied. }
  ERROR_ACCESS_DENIED = 5;

  { The handle is invalid. }
  ERROR_INVALID_HANDLE = 6;
  // ... and so on

A description of the Win32 error can be obtained via the FormatMessage function. There is (specifically for our case) a more convenient wrapper in Delphi for this system function with a bunch of parameters: the SysErrorMessage function. It returns the human-readable description of the passed Win32 error code. By the way, note that messages are returned localized. In other words, if you have Russian Windows, then the messages will be in Russian. If English - in English.

Summarizing what has been said, you have to call such functions like this:

{ prepare the WndClass }
ClassAtom := RegisterClassEx(WndClass);
if ClassAtom = 0 then
begin
  // some error occurred, failure reason is indicated by GetLastError
  Application.MessageBox(
    PChar('There was an error: ' + SysErrorMessage(GetLastError)), 
    PChar('Error'), MB_OK or MB_ICONSTOP);
  Exit;
end;
// ... continue normal execution

As in the memory management case - it is the same: do not follow the example of Windows. This style has long been outdated. And here's what's wrong with him (it is not a complete list):

To call a function, two calls are required: the function itself and the GetLastError (add to this the need to call the function itself twice to get memory from it - it turns out to be a terrible horror as much as four function calls instead of one);
You need to explicitly write a check like if something then error. And if you forget to write this code, you will get a bug: your program will continue executing ignoring the error. Probably corrupting the data and making it difficult to localize the bug (the visible problem will happen later);
- If-like checks also clog the code visually;
If in case of an error you need to free some resources, and even if there are several of them and there are also several function calls, then the correct code for freeing resources can become very non-trivial;
You can not pass any additional information. For example, you can not specify in any way which argument is incorrect, or which file you do not have access to;
- You have no way of knowing which function failed, whether it was the function you called, or maybe some other function that the one you called might have called;
The debugger will not notify you of the problem in any way (although, hypothetically, you could put a breakpoint on the GetLastError).

Despite all the disadvantages, error codes have a plus: since they are just numbers, they are understandable to any programming language. In other words, error codes are compatible between different languages.

Exceptions

(and why not to use them)

Exceptions don't have many of the disadvantages of error codes:

Exceptions do not need to be explicitly checked, the default reaction is an error response;
- The program is not "polluted" with the check code, it is taken out of your main code;
Easy to release resources (via try-finally);
Exceptions are easy to extend, inherit, add additional fields, make nested exceptions;
The debugger will notify you when an exception occurs;
- You can assign your code to diagnose exceptions (the so-called exception tracer).

But despite all the pluses, exceptions have one significant minus, which crosses out all the pluses (in relation to the DLL API).

Recall how exceptions are raised in Delphi:

var
  E: Exception;
begin
  E := EMyExceptionClass.Create('Something');
  raise E;
end;

I split the typical "raise EMyExceptionClass.Create('Something');" line into two to make the problem even more obvious. We create a Delphi object (exception) and "throw" it. And whoever wants to handle this exception does this:

except
  on E: EMyException do
  begin
    ShowMessage(E.Message);
  end; // - E will be deleted here
end;

It means that the Delphi object is passed from the callee (DLL) where the exception is thrown to the caller (exe) where the exception is handled. As we learned earlier (see the Data Types section above), this is a problem. Other programming languages don't know what a Delphi object is, nor how to read it, nor how to delete it. Even Delphi itself doesn't always know this (for example, if an exception is thrown by code built on Delphi 7 but caught by code built on Delphi XE, or vice versa). Other programming languages use similar constructs: an exception is represented by an object. Accordingly, Delphi code has no idea how to work with objects in other languages.

In other words, exceptions should not be used due to language incompatibilities.

Corollary 1: Exceptions should not leave your DLL.

Corollary 2: You must catch all exceptions in your exported functions.

Corollary 3: all exported functions must have the global construct try-except.

function GetDynData(const AFlags: DWORD; out AData: IData): BOOL; stdcall;
begin
  try
    // ... function's code, useful payload ... 
    Result := True;
  except
    // ... exception handling ...
    Result := False;
  end;
end;

What can and should be used

(and which calling convention to use)

If we can't use error codes and we can't use exceptions, then what should we use? Well, we need to use their combination - and here is how it looks.

Delphi has built-in compiler magic that can wrap any function in a hidden try-except block with an automatic (hidden) call to the processing function. And there is a compiler magic that works the other way around: on the returned error code, it automatically raises the appropriate exception.

Before we get to know this magic, we need to get acquainted with error codes in the form of the HRESULT type. The HRESULT is also a number, but now of the Integer type. The HRESULT is no longer just an error code, it consists of several parts, which we will not go into in detail, but suffice it to say that they include the error code itself (what used to be Win32 code), a sign success or failure, identifier of the error agent. Error codes typically start with the E_ prefix (for example, E_FAIL, E_UNEXPECTED, E_ABORT or E_ACCESSDENIED), and success codes typically start with the S_ prefix (for example, S_OK or S_FALSE). It is easy to determine the success of the HRESULT code by comparing it with zero: HRESULT error codes must be less than zero.

Highlighting the success/error indicator means that now there is no need for the function to return only the success/failure (via BOOL), and the error code itself - through a separate function (GetLastError). Now the function can return both information at once, in one call:

function GetDynData(const AFlags: DWORD; out AData: IData): HRESULT; stdcall;
begin
  try
    // ... function's code, useful payload ... 
    Result := S_OK;
  except
    // ... exception handling ...
    Result := E_FAIL; // some error code
  end;
end;

Along with the introduction of the HRESULT type, the IErrorInfo interface was added - which allows you to associate additional information with the returned HRESULT: arbitrary description, GUID of the raising party (interface), the location of the error (arbitrary line), help. You don't even need to implement this interface, the system already has an object ready - returned by the CreateErrorInfo function.

Finally, Delphi has the already mentioned compiler magic that can make writing such code easier. To do this, the function must have a calling convention stdcall and return the HRESULT type. If before the function returned some Result, then this Result should be converted to the last out-parameter, for example:

// Was:
function GetDynData(const AFlags: DWORD): IData;

// Became:
function GetDynData(const AFlags: DWORD; out AData: IData): HRESULT; stdcall;

If a function satisfies these requirements, then you can declare it like this:

function GetDynData(const AFlags: DWORD): IData; safecall;

This would be binary equivalent (i.e. fully compatible) to:

function GetDynData(const AFlags: DWORD; out AData: IData): HRESULT; stdcall;

By declaring a function as safecall you turn on compiler magic for it, namely:

The returned result will be automatically converted to the last out parameter;
The function will implicitly return the HRESULT (and possibly IErrorInfo);

The function's call will be wrapped in an if-check on the return code. If an erroneous HRESULT is received, an exception will be raised:

var
  Data: IData;
begin
  Data := GetDynData(Flags); // throwns exception when error occurs
  // execution continues only when there is no error

The function itself will be wrapped in a hidden try-except block that converts the exception to HRESULT (and possibly to IErrorInfo):

function GetDynData(const AFlags: DWORD): IData; safecall;
begin 
  // ... function's code, useful payload ...
end; // - a hidden try-except block

As you can see, with this compiler support, you can write code almost as if it was a regular function in a regular Delphi unit. And the best part is that other programming languages can use a similar approach. Of course, other programming language may not have a similar compiler magic, but any language is perfectly capable of taking the HRESULT of the stdcall function and parsing it (perhaps along with IErrorInfo).

How to use `safecall` correctly

Now that we've covered the benefits of the safecall, it's time for a fly in the ointment. The fact is that the safecall magic works in a minimal mode "out of the box". And to get maximum benefit from it, we need to take additional steps. Luckily, they only need to be made once and can be reused in the future.

Item number one: simple exported functions:

procedure DoSomething; safecall;
begin
  // ... function's code, useful payload ...
end;

exports
  DoSomething;

Unfortunately, the compiler does not allow customizing the process of converting an exception to HRESULT for ordinary functions, always returning a fixed code and losing additional error information. Therefore, instead of exported functions, you need to use interfaces with methods. Before:

procedure DoSomething; safecall;
begin
  // ... function's code, useful payload ...
end;

function GetDynData(const AFlags: DWORD): IData; safecall;
begin 
  // ... function's code, useful payload ...
end;

function DoSomethingElse(AOptions: IOptions): BSTR; safecall;
begin 
  // ... function's code, useful payload ...
end;

exports
  DoSomething,
  GetDynData,
  DoSomethingElse;

After:

type
  IMyDLL = interface 
  ['{C5DBE4DC-B4D7-475B-9509-E43193796633}']
    procedure DoSomething; safecall;
    function GetDynData(const AFlags: DWORD): IData; safecall;
    function DoSomethingElse(AOptions: IOptions): BSTR; safecall;
  end;

  TMyDLL = class(TInterfacedObject, IMyDLL)
  protected
    procedure DoSomething; safecall;
    function GetDynData(const AFlags: DWORD): IData; safecall;
    function DoSomethingElse(AOptions: IOptions): BSTR; safecall;
  end;

procedure TMyDLL.DoSomething; safecall;
begin
  // ... function's code, useful payload ...
end;

function TMyDLL.GetDynData(const AFlags: DWORD): IData; safecall;
begin 
  // ... function's code, useful payload ...
end;

function TMyDLL.DoSomethingElse(AOptions: IOptions): BSTR; safecall;
begin 
  // ... function's code, useful payload ...
end;

function GetFunctions(out AFunctions: IMyDLL): HRESULT; stdcall;
begin
  try
    AFunctions := TMyDLL.Create;
    Result := S_OK;
  except
    on E: Exception do
      Result := HandleSafeCallException(E, ExceptAddr);
  end;
end;

exports
  GetFunctions;

where HandleSafeCallException is our function, which we will describe below.

As you can see, we have placed all exported functions in a single interface (object) - this will allow us to set up/control the process of converting exceptions to HRESULT. In this case, the DLL exports the only function that we had to write manually, without safecall - which also allowed us to control the conversion process. Don't forget that it is binary compatible with safecall, so if you want to use this DLL in Delphi you can do this:

function GetFunctions: IMyDLL; safecall; external 'MyDLL.dll';

and it will work just fine.

For objects, when an exception is thrown in a safecall method, the compiler calls the TObject.SafeCallException virtual method which does nothing useful by default and which we can replace with our own method:

type
  TMyDLL = class(TInterfacedObject, IMyDLL)
  protected
    procedure DoSomething; safecall;
    function GetDynData(const AFlags: DWORD): IData; safecall;
    function DoSomethingElse(AOptions: IOptions): BSTR; safecall;
  public
    function SafeCallException(ExceptObject: TObject; ExceptAddr: Pointer): HResult; override;
  end;

function TMyDLL.SafeCallException(ExceptObject: TObject; ExceptAddr: Pointer): HResult; 
begin
  Result := HandleSafeCallException(ExceptObject, ExceptAddr);
end;

Further, when the code calls a safecall method, the compiler wraps the method's call in a CheckAutoResult wrapper, which (in case of erroneous code) raises an exception through the SafeCallErrorProc global variable function, which, again, we can replace with our own:

procedure RaiseSafeCallException(ErrorCode: HResult; ErrorAddr: Pointer);
begin
  // ... our code ...
end;

initialization
  SafeCallErrorProc := RaiseSafeCallException;
end.

Now we just need to make our HandleSafeCallException and RaiseSafeCallException work as a pair and do something useful.

First we need two helper wrapper functions:

uses
  ActiveX; // or Ole2

function SetErrorInfo(const ErrorCode: HRESULT; const ErrorIID: TGUID; 
  const Source, Description, HelpFileName: WideString;
  const HelpContext: Integer): HRESULT;
var
  CreateError: ICreateErrorInfo;
  ErrorInfo: IErrorInfo;
begin
  Result := E_UNEXPECTED;
  if Succeeded(CreateErrorInfo(CreateError)) then
  begin
    CreateError.SetGUID(ErrorIID);
    if Source <> '' then
      CreateError.SetSource(PWideChar(Source));
    if HelpFileName <> '' then
      CreateError.SetHelpFile(PWideChar(HelpFileName));
    if Description <> '' then
      CreateError.SetDescription(PWideChar(Description));
    if HelpContext <> 0 then
      CreateError.SetHelpContext(HelpContext);
    if ErrorCode <> 0 then
      Result := ErrorCode;
    if CreateError.QueryInterface(IErrorInfo, ErrorInfo) = S_OK then
      ActiveX.SetErrorInfo(0, ErrorInfo);
  end;
end;

procedure GetErrorInfo(out ErrorIID: TGUID; out Source, Description, HelpFileName: WideString; out HelpContext: Longint);
var
  ErrorInfo: IErrorInfo;
begin
  if ActiveX.GetErrorInfo(0, ErrorInfo) = S_OK then
  begin
    ErrorInfo.GetGUID(ErrorIID);
    ErrorInfo.GetSource(Source);
    ErrorInfo.GetDescription(Description);
    ErrorInfo.GetHelpFile(HelpFileName);
    ErrorInfo.GetHelpContext(HelpContext);
  end
  else
  begin
    FillChar(ErrorIID, SizeOf(ErrorIID), 0);
    Source := '';
    Description := '';
    HelpFileName := '';
    HelpContext := 0;
  end;
end;

As you can easily imagine, they are intended to pass and receive additional information along with HRESULT.

Next, we need a way to somehow pass the class name of the exception. You can do this in different ways. For example, pass it directly to HRESULT. To do this, it needs to be encoded. For example, like this:

uses
  ComObj, // for the EOleSysError and EOleException
  VarUtils; // for the ESafeArrayError

const
  // ID for our DLL API rules
  ThisDllIID: TGUID   = '{AA76E538-EF3C-4F35-9914-B4801B211A6D}';
  // "Customer" bit, it is always 0 for Microsoft-defined codes
  CUSTOMER_BIT        = 1 shl 29;
  // Delphi uses this value to pass EAbort
  // It is assumed that E_Abort should show "Aborted" message,
  // while EAbortRaisedHRESULT should be handled silently.
  EAbortRaisedHRESULT = HRESULT(E_ABORT or CUSTOMER_BIT);

function Exception2HRESULT(const E: TObject): HRESULT;

  function NTSTATUSFromException(const E: EExternal): DWORD;
  begin
    // ...
  end;

begin
  if E = nil then
    Result := E_UNEXPECTED
  else
  if not E.InheritsFrom(Exception) then
    Result := E_UNEXPECTED
  else
  if E.ClassType = Exception then
    Result := E_FAIL
  else
  if E.InheritsFrom(ESafecallException) then
    Result := E_FAIL
  else
  if E.InheritsFrom(EAssertionFailed) then
    Result := E_UNEXPECTED
  else
  if E.InheritsFrom(EAbort) then
    Result := EAbortRaisedHRESULT
  else
  if E.InheritsFrom(EOutOfMemory) then
    Result := E_OUTOFMEMORY
  else
  if E.InheritsFrom(ENotImplemented) then
    Result := E_NOTIMPL
  else
  if E.InheritsFrom(ENotSupportedException) then
    Result := E_NOINTERFACE
  else
  if E.InheritsFrom(EOleSysError) then
    Result := EOleSysError(E).ErrorCode
  else
  if E.InheritsFrom(ESafeArrayError) then
    Result := ESafeArrayError(E).ErrorCode
  else
  if E.InheritsFrom(EOSError) then
    Result := HResultFromWin32(EOSError(E).ErrorCode)
  else
  if E.InheritsFrom(EExternal) then
    if Failed(HRESULT(EExternal(E).ExceptionRecord.ExceptionCode)) then
      Result := HResultFromNT(Integer(EExternal(E).ExceptionRecord.ExceptionCode))
    else
      Result := HResultFromNT(Integer(NTSTATUSFromException(EExternal(E))))
  else
    Result := MakeResult(SEVERITY_ERROR, FACILITY_ITF, Hash(E.ClassName)) or CUSTOMER_BIT;
end;

Here we are checking for a few special predefined classes, and we also have the ability to pass Win32 codes and hardware exception codes directly. For all other (Delphi specific) exception classes, we use the hash on the class name along with FACILITY_ITF. As a hash, you can use, for example, SDBM - this is a very simple hash function with good randomization of the result. Of course, you can use any other method - for example, just manually extract and fix the codes for each exception class.

HRESULTs with FACILITY_NULL and FACILITY_RPC codes have a generic value because they are defined by Microsoft. HRESULT with FACILITY_ITF code are defined by the interface function or method from which they are returned. This means that the same 32-bit value in FACILITY_ITF but returned by two different interfaces can have different meanings. In this way, Microsoft can define multiple generic error codes while still allowing other programmers to define new error codes without fear of conflict. The coding convention looks like this:

HRESULT with codes other than FACILITY_ITF can only be defined by Microsoft;

HRESULT of FACILITY_ITF are defined solely by the implementer of the interface or function that returns HRESULT. To avoid conflicting HRESULT, whoever defines an interface is responsible for coordinating and publishing the HRESULT codes associated with that interface;

All HRESULT defined by Microsoft have an error code value in the $0000-$01FF range. Although you can use any code with FACILITY_ITF, it is recommended to use values in the $0200-$FFFF range. This recommendation is intended to reduce confusion with Microsoft codes.

That's why in the code above we also defined ThisDllIID which is an "interface" identifier that gives meaning to returned codes of type FACILITY_ITF. This value must be passed as ErrorIID to the SetErrorInfo defined above.

The 29th "Customer" bit was originally a reserved bit, which was later allocated to be used as a flag indicating whether the code is defined by Microsoft (0) or by a third party (1). In a way, this bit duplicates FACILITY_ITF. Usually even third party developers only use FACILITY_ITF. In this case, we set it to reduce possible problems with bad code (which does not take into account the GUID of the interface).

Wverything is a little more complicated with the reverse conversion (code to exception): we need tables to search for the exception class by code. A simple implementation might look like this:

function HRESULT2Exception(const E: HRESULT): Exception;

  function MapNTStatus(const ANTStatus: DWORD): ExceptClass;
  begin
    // ...
  end;

  function MapException(const ACode: DWORD): ExceptClass;
  begin
    // ...
  end;

var
  NTStatus: DWORD;
  ErrorIID: TGUID;
  Source: WideString;
  Description: WideString;
  HelpFileName: WideString;
  HelpContext: Integer;
begin
  if GetErrorInfo(ErrorIID, Source, Description, HelpFileName, HelpContext) then
  begin
    if Pointer(StrToInt64Def(Source, 0)) <> nil then
      ErrorAddr := Pointer(StrToInt64(Source));
  end
  else
    Description := SysErrorMessage(DWORD(E));

  if (E = E_FAIL) or (E = E_UNEXPECTED) then
    Result := Exception.Create(Description)
  else
  if E = EAbortRaisedHRESULT then
    Result := EAbort.Create(Description)
  else
  if E = E_OUTOFMEMORY then
  begin
    OutOfMemoryError;
    Result := nil;
  end
  else
  if E = E_NOTIMPL then
    Result := ENotImplemented.Create(Description)
  else
  if E = E_NOINTERFACE then
    Result := ENotSupportedException.Create(Description)
  else
  if HResultFacility(E) = FACILITY_WIN32 then
  begin
    Result := EOSError.Create(Description);
    EOSError(Result).ErrorCode := HResultCode(E);
  end
  else
  if E and FACILITY_NT_BIT <> 0 then
  begin
    // Get exception's class by code
    NTStatus := Cardinal(E) and (not FACILITY_NT_BIT);
    Result := MapNTStatus(NTStatus).Create(Description);

    // Create a dummy ExceptionRecord just in case
    ReallocMem(Pointer(Result), Result.InstanceSize + SizeOf(TExceptionRecord));
    EExternal(Result).ExceptionRecord := Pointer(NativeUInt(Result) + Cardinal(Result.InstanceSize));
    FillChar(EExternal(Result).ExceptionRecord^, SizeOf(TExceptionRecord), 0);

    EExternal(Result).ExceptionRecord.ExceptionCode := cDelphiException;
    EExternal(Result).ExceptionRecord.ExceptionAddress := ErrorAddr;
  end
  else
  if (E and CUSTOMER_BIT <> 0) and
     (HResultFacility(E) = FACILITY_ITF) and
     CompareMem(@ThisDllIID, @ErrorIID, SizeOf(ErrorIID)) then
    Result := MapException(HResultCode(E)).Create(Description)
  else
    Result := EOleException.Create(Description, E, Source, HelpFileName, HelpContext);
end;

In general, the code is fairly straightforward, with the exception of hardware exceptions. We make emulation for them.

Also note that the Source field of the IErrorInfo interface must point to the location where the error occurred. This field is arbitrary and is determined by the interface developer (ie, again, by GUID). In this case, we just write the address of the exception there. But, for example, if you use an exception tracer (such as EurekaLog), you can write the call stack there.

Then with the above helper functions, our HandleSafeCallException and RaiseSafeCallException become trivial:

function HandleSafeCallException(ExceptObj: TObject; ErrorAddr: Pointer): HRESULT;
var
  ErrorMessage: String;
  HelpFileName: String;
  HelpContext: Integer;
begin
  if ExceptObj is Exception then
    ErrorMessage := Exception(ExceptObj).Message
  else
    ErrorMessage := SysErrorMessage(DWORD(E_FAIL));
  if ExceptObj is EOleException then
  begin
    HelpFileName := EOleException(ExceptObj).HelpFile;
    HelpContext := EOleException(ExceptObj).HelpContext;
  end
  else
  begin
    HelpFileName := '';
    if ExceptObj is Exception then
      HelpContext := Exception(ExceptObj).HelpContext
    else
      HelpContext := 0;
  end;

  Result := SetErrorInfo(Exception2HRESULT(ExceptObj), ThisDllIID,
    '$' + IntToHex(NativeUInt(ErrorAddr), SizeOf(ErrorAddr) * 2), ErrorMessage,
    HelpFileName, HelpContext);
end;

procedure RaiseSafeCallException(ErrorCode: HResult; ErrorAddr: Pointer);
var
  E: Exception;
begin
  E := HRESULT2Exception(ErrorCode, ErrorAddr);
  raise E at ErrorAddr;
end;

Note: in our model, we do not use help fields of the IErrorInfo interface.

It should be noted that if an interface uses HRESULT and IErrorInfo together, then it should also implement the ISupportErrorInfo interface. Some programming languages require this. By calling ISupportErrorInfo.InterfaceSupportsErrorInfo, the client side can determine that an object supports additional information.

And the last point - in the Delphi implementation for Windows 32-bit there is nasty bug that doesn't exist in 64-bit RTL, as well as on other platforms. The fix for this bug is included in the code examples at the link at the end of the article.

DllMain Workaround

The DllMain is a special function in a DLL that is called by the system when the DLL is loaded into, unloaded from a process (and attached/detached to/from a thread). For example, the initialization and finalization sections of your Delphi modules are executed inside DllMain.

The problem is that DllMain is a very special function. It is called while holding the critical section of the loader (modules) of the operating system. In long and detailed terms - see the links at the end of this paragraph, and in short: DllMain is a weapon from which you can easily shoot yourself. There are not many things that can be done legally in DllMain. But it's incredibly easy to do something forbidden - you constantly need to be sure that this very function that you just called can never, under any circumstances, do something forbidden. This makes it incredibly difficult to use code written elsewhere. The compiler won't tell you anything. And the code will most of the time work like it should... but sometimes it will crash or freeze.

The solution to the problem is to do nothing in DllMain (read: don't write code in initialization and finalization sections of your units when you create a DLL).

Instead, you need to make separate DLL initialization and finalization functions. You need to do them even if your DLL doesn't need any initialization or cleanup steps. After all, such a need may arise in the future, and if you do not provide separate initialization and finalization functions in your API, you will not be able to solve this problem later.

Here is the code template:

// In headers:
type
  IMyDll = interface
  ['{C5DBE4DC-B4D7-475B-9509-E43193796633}']
    procedure InitDLL(AOptional: IUnknown = nil); safecall;
    procedure DoneDLL; safecall;
    // ...
  end;

// In DLL:

type
  TInitFunc = procedure(const AOptional: IUnknown);
  TDoneFunc = procedure;
  TInitDoneFunc = record
    Init: TInitFunc;
    Done: TDoneFunc; 
  end;

procedure RegisterInitFunc(const AInitProc: TInitFunc; const ADoneFunc: TDoneFunc = nil);

// ...

var
  GInitDoneFuncs: array of TInitDoneFunc;

procedure RegisterInitFunc(const AInitProc: TInitFunc; const ADoneFunc: TDoneFunc);
begin
  SetLength(GInitDoneFuncs, Length(GInitDoneFuncs) + 1);
  GInitDoneFuncs[High(GInitDoneFuncs)].Init := AInitProc;
  GInitDoneFuncs[High(GInitDoneFuncs)].Done := ADoneFunc;
end;

procedure TMyDLL.InitDLL(AOptional: IUnknown); safecall;
var
  X: Integer;
begin
  for X := 0 to High(GInitDoneFuncs) do
    if Assigned(GInitDoneFuncs[X].Init) then
      GInitDoneFuncs.Init(AOptional);
end;

procedure TMyDLL.DoneDLL; safecall;
var
  X: Integer;
begin
  for X := 0 to High(GInitDoneFuncs) do
    if Assigned(GInitDoneFuncs[X].Done) then
      GInitDoneFuncs.Done;
end;

// In your units:

procedure InitUnit(const AOptional: IUnknown);
begin
  // ... code from unit's initialization sections
end;

procedure DoneUnit;
begin
  // ... code from unit's finalization section
end;

initialization
  RegisterInitFunc(InitUnit, DoneUnit);
end;

The AOptional parameter is designed for possible future use. It is not used in the code above, but later (in the next version of the DLL) you can use it to pass initialization parameters. IUnknown is the base interface from which all other interfaces are inherited (i.e. some analogue of TObject for interfaces).

I hope this code is clear enough. Of course, it must be distributed among different units and sections. Interface - in headers, RegisterInitFunc declaration - in interface of the common DLL module, you need to call it from the initialization section of other units.

Of course, your SDK documentation should say that the user (client) of your DLL must call the InitDLL method immediately after loading your DLL with the LoadLibrary function and call the DoneDLL just before the DLL is unloaded by FreeLibrary:

var
  DLL: HMODULE;
  DLLApi: IMyDll;
begin
  DLL := LoadLibrary('MyDLL.dll');
  Win32Check(DLL <> 0);
  try
    DLLApi.InitDLL(nil);

    // working with DLL, for example, calling DLLApi.GetDynData

  finally
    DLLApi.DoneDLL;
    DLLApi := nil;
    FreeLibrary(DLL);
  end;
end;

More information about the DllMain:

Callback Functions

A callback function - passing the executable code as one of the parameters of another code. For example, if you want to set a timer using the Windows API, you can call SetTimer function, passing it a pointer to your own function, which will be the callback function. The system will call your function every time the timer fires:

procedure MyTimerHandler(Wnd: HWND; uMsg: UINT; idEvent: UINT_PTR; dwTime: DWORD); stdcall;
begin
  // Will be called after 100 ms timeout
end;

procedure TForm1.Button1Click(Sender: TObject);
begin
  SetTimer(Handle, 1, 100, @MyTimerHandler);
end;

Here's another example: if you want to find all windows on the desktop, you can use the EnumWindows function:

function MyEnumFunc(Wnd: HWND; lpData: LPARAM): Bool; stdcall;
begin
  // Will be called for each found window
end;

procedure TForm1.Button1Click(Sender: TObject);
begin
  EnumWindows(@MyEnumFunc, 0);
end;

Since the callback function usually performs the same task as the code that sets it up, it turns out that both pieces of code need to work with the same data. Therefore, the data from the setting code must somehow be passed to the callback function (or visa versa). For this purpose, so-called user parameters are provided in the callback functions: it is either a pointer or an integer (necessarily of the Native(U)Int type, but not just (U)Int), which are not used by the API itself in any way and are transparently passed to the callback function. Or (in rare cases) it can be some value that uniquely identifies the function's call.

For example, SetTimer has idEvent and EnumWindows has lpData. We can use these parameters to pass arbitrary data. For example, here is how you can find all windows of a given class:

type
  PEnumArgs = ^TEnumArgs;
  TEnumArgs = record
    ClassName: String;
    Windows: TStrings;
  end;

function FindWindowsOfClass(Wnd: HWND; lpData: LPARAM): Bool; stdcall;
var
  Args: PEnumArgs;
  WndClassName, WndText: String;
begin
  Args := Pointer(lpData);

  SetLength(WndClassName, Length(Args.ClassName) + 2);
  SetLength(WndClassName, GetClassName(Wnd, PChar(WndClassName), Length(WndClassName)));
  if WndClassName = Args.ClassName then
  begin
    SetLength(WndText, GetWindowTextLength(Wnd) + 1);
    SetLength(WndText, GetWindowText(Wnd, PChar(WndText), Length(WndText)));
    Args.Windows.Add(Format('%8x : %s', [Wnd, WndText]));
  end;

  Result := True;
end;

procedure TForm1.Button1Click(Sender: TObject);
var
  Args: TEnumArgs;
begin
  // Edit can contain values like:
  // 'TForm1', 'IME', 'MSTaskListWClass', 'Shell_TrayWnd', 'TTOTAL_CMD', 'Chrome_WidgetWin_1'
  Args.ClassName := Edit1.Text;  
  Args.Windows   := Memo1.Lines;

  Memo1.Lines.BeginUpdate;
  try
    Memo1.Lines.Clear;
    EnumWindows(@FindWindowsOfClass, LPARAM(@Args));
  finally
    Memo1.Lines.EndUpdate;
  end;
end;

Note: here's another example of how not to do it - don't do it like in Windows. If you just need to get a list of something - don't make a callback, just return the list in an array (wrap it in an interface or pass it as a block of memory - as discussed above). The callback function should only be used if creating the list can take a long time and you don't need all the elements. Then the callback function can return the "stop" flag without completing the list to the end.

Note: some analogue of user-parameters are Tag and Data properties, although their use is not always ideologically correct (correct: create a derived class).

The conclusion follows from the above: if your API needs to make a callback function, then it must have a custom Pointer size parameter that will not be used by your API. For example:

// Incorrect!
type
  TNotifyMeProc = procedure; safecall;

  IMyDllAPI = interface 
    // ...
    procedure NotifyMe(const ANotifyEvent: TNotifyMeProc); safecall;
  end;

// Correct
type
  TNotifyMeProc = procedure(const AUserArg: Pointer); safecall;

  IMyDllAPI = interface 
    // ...
    procedure NotifyMe(const ANotifyEvent: TNotifyMeProc; const AUserArg: Pointer = nil); safecall;
  end;

And if you forget to do this, the caller will have to use ugly hacks to get around your bad API design.

Naturally, instead of a function + parameter, you can just use an interface:

// Correct
type
  INotifyMe = interface
  ['{07FA30E4-FE9B-4ED2-8692-1E5CFEE4CF3F}']
    procedure Notify; safecall;
  end;

  IMyDllAPI = interface 
    // ...
    procedure NotifyMe(const ANotifyEvent: INotifyMe); safecall;
  end;

This is preferable, because error handling via safecall in interfaces is simpler, and the interface can contain as many parameters as you like, and it is even more convenient to integrate with objects (form). For example:

type
  TForm1 = class(TForm, INotifyMe)
    // ...
    procedure Notify; safecall;
  private
    FAPI: IMyDllAPI;
  public
    function SafeCallException(ExceptObject: TObject; ExceptAddr: Pointer): HResult; override;
  end;

// ...

procedure TForm1.FormCreate(Sender: TObject); 
begin
  // ... load DLL, get API

  FAPI.NotifyMe(Self); // Ask DLL to call us on some event 
end;

procedure TForm1.Notify; 
begin
  ShowMessage('Something just happenned');
  // Our form is available here (in the callback),
  // so we can just use it, no need to pass it manually
end;

Other Rules

If you are not only developing but also using a DLL, then load the DLL correctly. I won't go into details here, as it deserves its own article, but you can take a look at the LoadDLL function from the sample code below: do NOT use LoadLibrary!;
If for some reason you don't use safecall then don't return complex types via Result, make it an out parameter. The problem is that Delphi and MS Visual C++ disagree on how to interpret the result returned by reference by a stdcall function: as var or as out. Accordingly, for safecall there is no such problem, since Result for it is always Integer (HRESULT) - a simple type, for which var and out are equivalent;
All APIs must have a unique IID/GUID (non-API interfaces (not mentioned in headers) might not have a GUID, although I would recommend always specifying an IID). You can create a GUID to use as an IID (Interface ID) by pressing Ctrl + Shift + G in the Delphi code editor - this combination will insert an expression like ['{C5DBE4DC-B4D7-475B-9509- E43193796633}'] (of course, each time with a unique GUID) directly below the cursor in the editor;

Once you have published some type (interface), i.e. released your DLL with this interface - you shouldn't change it. If you need to expand or change it, you introduce a new interface (a new version of the interface), but do not change the old one

// Was:
type
  IMyDLL = interface
  ['{C5DBE4DC-B4D7-475B-9509-E43193796633}']
    procedure InitDLL(AOptional: IUnknown = nil); safecall;
    procedure DoneDLL; safecall;
    function GetDynData(const AFlags: DWORD): IData; safecall;
  end;
  
// You can't do that after publishing a production build:
type
  IMyDLL = interface
  ['{C5DBE4DC-B4D7-475B-9509-E43193796633}']
    procedure InitDLL(AOptional: IUnknown = nil); safecall;
    procedure DoneDLL; safecall;
    procedure DoSomething; safecall; // was added
    function GetDynData(const AFlags: DWORD): IData; safecall;
  end;

// However, you can do that:
type
  IMyDLLv1 = interface
  ['{C5DBE4DC-B4D7-475B-9509-E43193796633}']
    procedure InitDLL(AOptional: IUnknown = nil); safecall;
    procedure DoneDLL; safecall;
    function GetDynData(const AFlags: DWORD): IData; safecall;
  end;

  IMyDLLv2 = interface(IMyDLLv1)
  ['{69E77989-64DC-4177-975C-487818598C70}']
    procedure DoSomething; safecall; // added
  end;

If a function or method returns an interface, then don't do this:
```
// Incorrect!
function GetSomething: ISomething; safecall;

// ...

var
  Something: ISomething;
begin
  Something := GetSomething;
```
Surely, it is a convenient solution in the beginning: you can call functions "as usual" and even chain them into chains like Control.GetPicture.GetImage.GetColorInfo.GetBackgroundColor. However, this state of affairs will exist only in the very first version of the system. As soon as you start developing the system, you will start to have new interfaces. In the not so distant future, you will have a bunch of advanced interfaces, and the basic interfaces that were in the program initially, at the time of its birth, will implement only trivially uninteresting functions. As a result, very often the calling code will need new interfaces, not the original ones. What does it mean? This means that the code needs to call the original function, get the original interface, then ask it for a new one (via Supports/QueryInterface) and only then use the new interface. It turns out not so convenient, even rather inconvenient: we have a triple call (original + conversion + required). The best solution is for the calling code to tell the called function which interface it is interested in: the new one or the old one:
```
// Correct
procedure GetSomething(const AIID: TGUID; out Intf); safecall;

// ... 

var
  Something: ISomething;
begin
  GetSomething(ISomething, Something);
```

If an object implements an interface, then your code should not contain variables of this class. I.e.:

type
  TSomeObject = class(TSomeOtherClass, ISomeInterface)
  // ... 
  end;

var
  Obj: TSomeObject; // - incorrect!
  Obj: ISomeInterface; // - correct
begin
  Obj := TSomeObject.Create;
  // ...

If you're implementing an interface extension by inheritance, don't forget to explicitly list all of its ancestors in the implementing object. For example:

type
  ISomeInterfaceV1 = interface
  ['{A80A78ED-5836-49C4-B6C2-11F531103FE7}']
    procedure A;
  end;
 
  ISomeInterfaceV2 = interface(ISomeInterfaceV1) // ISomeInterfaceV2 is inherited from ISomeInterfaceV1
  ['{EBDD52A1-489B-4564-998E-09FCCF923F48}']
    procedure B;
  end;
 
  // Incorrect!
  TObj = class(TInterfacedObject, ISomeInterfaceV2) // ISomeInterfaceV2 is mentioned, but not ISomeInterfaceV1
  protected
    procedure A; 
    procedure B;
  end;

var
  SI1: ISomeInterfaceV1;
  SI2: ISomeInterfaceV2;
begin
  Supports(SI2, ISomeInterfaceV1, SI1);
  Assert(Assigned(SI1)); // will fire, since SI1 = nil (Supports returned False)
end;

A correct way would be:

  // Correct
  TObj = class(TInterfacedObject, ISomeInterfaceV1, ISomeInterfaceV2)
  // ...

It is not necessary to make the implementation of interface methods virtual:

type
  ISomeInterfaceV1 = interface
  ['{C25F72B0-0BC9-470D-8F43-6F331473C83C}']
    procedure A;
  end;

  TObj = class(TInterfacedObject, ISomeInterfaceV1)
  protected
    // Incorrect
    procedure A; virtual;
  end;

Do like so instead:

  TObj = class(TInterfacedObject, ISomeInterfaceV1)
  protected
    // Correct
    procedure A;
  end;

Do not use the const modifier with interface parameters:

// Incorrect!
procedure DoSomething(const AArg: ISomething); safecall;

// Correct
procedure DoSomething(AArg: ISomething); safecall;

Other unspoken rules.

Conclusion

Download sample DLL API here. The archive contains a group of two projects (a DLL and an application that uses it). The DLL implements an sample API with example functions. The SDK folder contains the SDK, which consists of:

SDK:
- SampleDLLHeaders.pas header file;
- CHM and PDF documentation (and project sources Help&Manual);
As well as the Delphi-specific support file DelphiSupport.pas.

Developers in other programming languages can use SampleDLLHeaders.pas and Delphi developers can use SampleDLLHeaders.pas + DelphiSupport.pas.

Headers are presented only in the form of Delphi code. Translation into other programming languages left as homework.

The DelphiSupport.pas module can be included both in the DLL and in applications that use it. It contains:

Processing safecall (along with fixing RSP-24652);
A base object TBaseObject for implementing interfaces with safecall processing support and debugging checks;
Prebuilt classes: TMalloc allocator and TNotify wrapper;
The function RegisterInitFunc for registering the initialization of modules in the DLL;
LoadDLL function for correct loading of the DLL.

The DLL API has sample functions:

Returning an array of strings GetData;
Returning dynamic memory GetMemory;
Callback function set by NotifyMe;
Error/Exception Test TryAbort, TryAccessViolation, etc

The calling application shows both "load-use-upload" and "load, use, upload".

What can you do with the "Assember" tab in bug reports? Is it even useful?

2023-08-12T16:51:00.006+01:00

We were contacted by a customer that claimed that his application worked fine until he added EurekaLog to it. Specifically, his application starts to raise an EAccessViolation exception with the following message:
Access violation at address 03DB472F in module 'Sample.exe'. Read of address 5653E4CC

The customer was kind enough to share the code mentioned in the call stack of the bug report:

function TContosoEventCollection.FindEvent(const AValue: TContosoEvent): Integer;
var
  X: Integer;
begin
  Result := -1;

  if not Assigned(FEvents) then
    Exit;

  for X := 0 to FEvents.Count - 1 do // - crashes here
  begin
    if SameMethod(AValue, FEvents[X]) then
    begin
      Result := X;
      Break;
    end;
  end;
end;

Where FEvents is the TList field in the TContosoEventCollection class.

As a reminder: the TList class is implemented in the RTL like this:

type
  TList = class(TObject)
  private
    FList: TPointerList;
    FCount: Integer;
  // ...
  protected
    function Get(Index: Integer): Pointer; // returns FList[Index]
  // ...  
  public  
    property Items[Index: Integer]: Pointer read Get write Put; default;
    property Count: Integer read FCount write SetCount;
  // ...
  end;

So, the code crashes while trying to read the FCount field of the TList class - which probably means that the TList object is not valid (in other words: trashed).

Well, the bug report can not be false-positive. So, what happenned? And why there is no access violation in the same application compiled without EurekaLog?

Quite often you would see message like this for memory errors:
Access violation at address ... in module '...'. Read of address DEADBEEF
Where the data address would match or be close to the DEADBEEF value - this is the debug marker that EurekaLog fills in the memory being deleted. In addition to DEADBEEF, you can also encounter other values: $CCCCCCCC, $FEEEFEEE, $FDFDFDFD, $FADEDEAD, $00009999. EurekaLog attempts to reserve at least one of them for debugging purposes and will use the first one for which the reservation succeeds. There may also be values close to them (i.e. debug marker + offset, e.g. DEADBE8F).

However, in this particular case: the data address is 5653E4CC - which does not match any known debugger marker. So, at the first glance it could be a valid data value.

Note that 5653E4CC is supposed to be an address of the TList's FCount field. Now, let's take a look at the "Assember" tab from EL's bug report:

; Line=3297 - Offset=23
; ---------------------
03DB472F  8B7808          MOV  EDI, [EAX+8]                 ; <-- EXCEPTION

Now we can see that the TList's FCount field has the offset of 8 from the start of the TList object. In other words: it is the second field in the class. Therefore, the address of the TList object itself (in other words: the FEvents field in customer's TContosoEventCollection object) is 5653E4CC - 8 = 5653E4C4.

Why is this important?

Well, the 5653E4C4 = 1448338628 and it is NOT divisible by 16. In fact, it is not even disisible by 8. It matters because allocation granularity on Delphi is at least 16 bytes.
(Note: very old IDEs like Delphi 5 had allocation granularity of 4)

Conclusion: 5653E4C4 can not be address of any TList object in customer's application. Which means that it is a completely trash value. (Otherwise, we might suspect that it could be a value of some TList object - the one that was already deleted.)

Summary: the FEvents (TList) field in customer's TContosoEventCollection object is trashed.

Let's dig further. Look at the "Assembler" tab again:

; ContosoUnit.TContosoEventCollection.FindEvent (Line=1234 - Offset=0)
; ---------------------------------------------------------
03DB4718  55              PUSH EBP
03DB4719  8BEC            MOV  EBP, ESP

This sounds like a start of the TContosoEventCollection.FindEvent method to me. And what do we know about Delphi methods? Well, they pass Self as the implicit first argument. And what do we know about arguments passing in x86? Well, the first argument is stored in the EAX CPU register. It is further confirmed by the same "Assember" tab:

03DB471F  8BF0            MOV  ESI, EAX

; if not Assigned(FEvents) then
03DB4728  8B4604          MOV  EAX, [ESI+4]
03DB472B  85C0            TEST EAX, EAX

We can clearly see as Self is being copied from EAX into ESI, and then ESI is being used to read the FEvents field (which, as we remember, is trashed) - which has offset of 4 (e.g. the very first field in the class - also confirmed by customer's source code).

So, when crash occurs, the Self must be stored in the ESI CPU register. Let's take a look at it: 00451C10.

Do you see anything wrong with it?

Well, while the 00451C10 value is divisible by 16, but customer's EXE loads at the default 00400000 address - which is awfully close to the 00451C10. In fact, customer's app has crashed at the 03DB472F address (see the original exception's message) - which is well inside reach from the 00400000, given size of customer's exe being more than 100'000'000 bytes (as inspected from the "Modules" tab). 100'000'000 = 05F5E100, so 00400000 + 05F5E100 = 0635E100 - way more than the 03DB472F. Therefore, any valid data/objects must have addresses only above 0635E100 (or below 00400000).

In other words: 00451C10 is a code address. It can not possibly be any data/TObject address.

Conclusion: customer's TContosoEventCollection object is trashed too, so no wonder we read trash data from it, so its FEvents/TList field also becomes trash. Customer was unlucky in the sense that the invalid value of the TContosoEventCollection object was, in fact, readable, so CPU could load the (trashed) FEvents field from it and only crashed later. If customer was lucky - he would crash immediately on access to TContosoEventCollection's FEvents field.

Summary: customer should look further up stack to the caller code: it is calling the FindEvent method on the invalid object value. From where does it reads/takes the TContosoEventCollection object? Whatever it was - it is trashed now.

The customer has reported that he was able to find and fix the issue armed with this information.

As for the question why there was no access violation in the same application compiled without EurekaLog - well, applications without EurekaLog have absolutely no memory checks in them! So most memory-related errors go unnoticed.

See also: How to read bug reports.

P.S. Read more stories like this one or read feedback from our customers.

Does EurekaLog support CLang/LLVM/64-bit?

2023-07-26T17:33:00.011+01:00

Short Answer

Yes, EurekaLog supports CLang and LLVM in both 32 and 64 bits - with some limitations. Exception is the very recent "Windows 64-bit (Modern)" platform, which was added into the RAD Studio 12 Athens since the major 12.1 update. The "Windows 64-bit (Modern)" platform is not supported yet.

Long Answer

History

The 64-bit Delphi is build on the classic Borland toolchain. EurekaLog 7 supported 64-bit Delphi since the very begining: the original release of EurekaLog 7.0.0.0 in 2012. Since many of our clients were using the new 64-bit platform, we were also able to improve its support over time. It was feature-complete in somewhere near 2014. Currently it does not have any limitations.

On the other hand, the 64-bit C++ Builder is build on entirely different toolchain: LLVM. Classic toolchain is not used for 64-bit C++ Builder. The CLang is LLVM's frontend for C++. Initially EurekaLog 7 did not have support for LLVM.

While 32-bit C++ Builder was also originally build on the classic Borland toolchain, Embarcadero has released RAD Studio 10 Seattle in 2015 with an option to use the LLVM-based toolchain for 32-bit C++ Builder. In other words, starting with RAD Studio 10 Seattle (2015+):

32-bit Delphi: classic only
64-bit Delphi: classic only
32-bit C++ Builder: classic OR LLVM - your choice
64-bit C++ Builder: LLVM only

Since now CLang was accessible in 32-bit, we also started implementing support for LLVM and CLang. However, not many of our clients use C++ Builder. And very few clients immediately switched to CLang/LLVM. Therefore, we also couldn't polish our CLang/LLVM support as quickly as Delphi's 64-bit support. However, a lot of time has passed and we can say with confidence that many of our clients use EurekaLog for CLang/LLVM today.

Support for 64-bit C++ Builder is a relatively recent addition. It was enabled in 2020. EurekaLog doesn't track usage statistics, so we don't know exactly how many of our clients are using 64-bit C++ Builder. But we can judge this indirectly: by the number of questions to our technical support. And judging by it: almost none of our clients use 64-bit C++ Builder. This means we don't get a lot of feedback and improvements to our 64-bit C++ Builder support are VERY slow.

In summary: while EurekaLog does support CLang, LLVM and 64-bit, you must understand that some aspects had more time to polish and evolve. For these historical reasons, the levels of maturnity (in order from high to low) are:

32-bit Delphi
32-bit C++ Builder on classic toolchain
64-bit Delphi
32-bit C++ Builder on LLVM toolchain (CLang)
64-bit C++ Builder
64-bit C++ Builder (Modern)

Technical details and limitations

As mentioned above, 32-bit and 64-bit Delphi support and 32-bit C++ Builder on classic toolchain are feature-complete and have no limitations.

Unfortunately, using LLVM (CLang) for 32 or 64-bits means that some exception info is missing. LLVM (or its implementation in C++ Builder) is very unpolished for exception tracing. Specifically, it does not set an exception address, it does not set a valid stack pointer and a frame - all those necessary and important values are just zeros. We really got into the wilds of workarounds and hacks, only to extract the address of the exception. Everything really hangs on straws and assumptions.

Classic C++ Builder is much better in this aspect. We are improving diagnostic as much as possible, so newer versions of EurekaLog should provide better info. But there may be something that is impossible to implement from our side. We highly recommend that you don't use LLVM on 32-bit, use classic compiler. Naturally, you are limited to LLVM only for 64-bit C++ Builder as there is no option to use classic compiler.

Therefore, stack frames based methods will not work if you are using LLVM/CLang compiler (in other words: "Use classic compiler" option is disabled). Select any RAW method for LLVM/CLang.

One other point to consider is the debug information. Delphi, C++ Builder and RAD Studio has an option to generate a text .map file, which contains debug information about the compiled module - such as unit, class, function names and line numbers. Such .map file is used by EurekaLog to compose debug information in EurekaLog's own format - designed for maximum access speed or minimum space. The issue is that .map files produced by the C++ Builder do not have line numbers - just names of units, classes, and functions:

EurekaLog is also able to read debug information in Turbo Debugger (TD32, TDS) format. If it is enabled for C++ Builder - EurekaLog will use it to extract line numbers. So, when using 32-bit C++ Builder on the classic toolchain - EurekaLog will be able to show line numbers in bug reports.
If you would use LLVM/CLang on Win32 (e.g. "Use Classic compiler" option is disabled) or 64-bit C++ Builder (which is LLVM/CLang-only) - then no TD32/TDS debug information will be available, as LLVM/clang generates DWARF debug information, not TD32/TDS. Currently EurekaLog is unable to read DWARF debug information, so there will be no line numbers in bug reports.

You can help us to fix this issue by voting for this entry:
[RSS-1496] No line numbers in map files for many platforms, while classic Win32 works fine.
[RSP-27359] No line numbers in map files for LLVM-based compilers.

Many libraries/components are not tested for memory bugs

2023-04-03T21:43:00.003+01:00

We were contacted by a customer, who claimed that EurekaLog causes Access Violation in a simple sample demo application.

Specifically, the application runs fine when compiled without EurekaLog and produces the expected results. But application crashes with "Access violation at address 00410759 in module 'DemoApp.exe'. Read of address 83EC8B59" when compiled with EurekaLog.

Unfortunately, the customer did not report any additional details, such as: EurekaLog version, IDE version, OS version, bug report file nor call stack, etc. However, we did know that the access violation exception happenned inside the System._IntfClear function.

Well, it doesn't take a genius to figure out that there is most likely a memory bug in the sample app's code. And it is probably something related to mixing manual/automatic management of object's lifecycle.

We have installed a demo version of the components in question and compiled a sample application with EurekaLog. Running the application and simply exiting it trigered the following error:

"Application made attempt to call method of already deleted object: $0430B610 OBJECT [TContosoDoc] 340 bytes"

while the call stack from the bug report looked like this:

System._IntfClear

System._FinalizeRecord

System.TObject.CleanupInstance

System.TObject.FreeInstance

System._ClassDestroy

Contoso.VCL.TContosoPropertiesForm.Destroy 2893[2]

System.TObject.Free

System.Classes.TComponent.DestroyComponents

Vcl.Forms.DoneApplication

System.SysUtils.DoExitProc

System._Halt0

Well, the error message is different, but the crash location is the same. Why is that?

There could be few reasons for that:

The customer did not report when and how the error occurs. Perhaps, he was seeing a different error in a different place.
The client could (correctly) assume that it was a memory bug somewhere, so he tried to "fix" the bug by disabling some of the EurekaLog's memory check options. Therefore, the client application's configuration could differ from defaults. And we were checking using the default settings.
The code that detects/shows the "call method of already deleted object" message relies on the fact that the released memory remains untouched. However, if some code allocates memory over this disposed memory, the check could not function, and you get a simple access violation instead. So, depending on how memory is allocated/disposed, the behaviour can change.

Anyway, the EurekaLog was able to show a second call stack for the same object: specifically, the second call stack shows where the object was originally destroyed:

ContosoDoc.TContosoCustomDoc.Destroy

System.Classes.TComponent.DestroyComponents

Vcl.Forms.DoneApplication

System.SysUtils.DoExitProc

System._Halt0

Just looking at these two call stack you can see the problem already:

The second call stack (actual deletion) mentions that the object in question was deleted "manually" by calling its destructor when components are cleaned up on app's shutdown.
The first call stack (access to already deleted object) mentions that the same object was also tried to be deleted automagically via an interface reference.

Thankfully, we don't need the source code for the component/library (which we don't have, because we are using demo/trial) to confirm that. The line number from the first call stack leads us directly to the problem:

constructor TContosoPropertiesForm.Create(AOwner: TComponent);
begin
  inherited;
  FDoc := TContosoDoc.Create(Self);
end;

destructor TContosoPropertiesForm.Destroy;
begin
  inherited;
end;

where the FDoc field is declared as:

private
  FDoc: IContosoDoc;

Do you see the problem?

The TContosoDoc will be deleted by the TContosoPropertiesForm, because the TContosoPropertiesForm (Self) was passed as an owner to the TContosoDoc. So, when the TContosoPropertiesForm deletes itself - it also deletes all owned sub-components, including the TContosoDoc.

But the reference to the TContosoDoc was also saved into the FDoc field. That should not be a problem if the field has the TContosoDoc type. But it has the IContosoDoc type. In other words, it is an interface! When interface goes out of scope, it dereferences, and the object is deleted when the reference count reaches zero.

You may know that the components (descendants from TComponent) override the automatic inteface management by saying "there is no reference counter". In other words, increasing and descreasing interface counter do absolutely nothing.

If so - why there is the crash then? The reason is that even the simple "there is no reference counter" behavior requires virtual method calls! Indeed, remember that IInterface/IUnknown is declared as:

type
  IInterface = interface
    ['{00000000-0000-0000-C000-000000000046}']
    function QueryInterface(const IID: TGUID; out Obj): HResult; stdcall;
    function _AddRef: Integer; stdcall;
    function _Release: Integer; stdcall;
  end;
  
  IUnknown = IInterface;

In other words, any interface in Delphi must implement the _AddRef and _Release methods, because all interfaces in Delphi descent from IInterface.

Another piece of the puzzle: the "there is no reference counter" behaviour is not implemented like "do not call the _AddRef/_Release methods". Instead, this behaviour is implemented like "the _AddRef/_Release methods do nothing". So, the _AddRef/_Release methods must be called.

If so - they must be implemented (as emtpy methods). And how do you implement interface methods? By using virtual methods:

type
  TInterfacedObject = class(TObject, IInterface)
  protected
    FRefCount: Integer;
    function QueryInterface(const IID: TGUID; out Obj): HResult; stdcall;
    function _AddRef: Integer; stdcall;
    function _Release: Integer; stdcall;
  end;

Yes, the _AddRef/_Release methods are non-virtual methods for the object (class). However, remember that interface is basically an abstract class, which means all of its methods are pure virtual. Which means that the mentioned methods will be virtual methods for the interface once it is implemented.

And how do you call a virtual method? Well, you have to look it up inside object's (interface's) virtual method table. But if the object/interface was already released then its virtual method table won't be accessible anymore. That is where the bug comes from. The code is not actually trying to delete already deleted object, but it is trying to say "interface goes out of scope, please decrease reference counter". Normally this would result in the "do nothing" behaviour, but in our case the "do nothing" behaviour could not be located, since its implementing object is already gone.

So, why it was not a problem without EurekaLog on board?

It's simple: deleting object means marking its memory as "empty". The memory itself is not gone. And its content stays the same. Therefore, any futher calls to _AddRef/_Release methods will be successful, since virtual method table still could be located.

Conclusion: it is a bug in library/component's demo code, which must be fixed. Simplest way is a workaround: set the FDoc field to nil as the first action in the TContosoPropertiesForm's destructor. One correct way to fix it is to change field's type to object (class), so interfaces will be created/disposed only when used. Another way is to remove ownership and implement the reference counting, so object's lifetime will be managed by interface field only.

Moral of the story: use either interfaces or objects, do not mix! E.g. if you use interfaces - do not store references to implementing objects. If you use objects - do not store interface references.

As you can imagine, many libraries and components come with memory-related bugs, because there is no build-in tools in Delphi to diagnose such issues. You need a 3rd party tool: debugging memory manager. Not every library/component vendor will go extra length to use 3rd party tool to test his code. This is true even for Delphi itself, as both VCL and FMX has similar memory bugs which usually stays hidden. For example: RSP-38694, RSP-30403, RSP-28294, RSP-10308, ...

So, what if you can't fix the 3rd party code? Well, you can hide the bug by disabling the memory checks in EurekaLog. We recommend that you keep the "Enable extended memory manager" option enabled and disable all other sub-options. Don't forget to set the "When memory is released" option to "Do nothing". Please note that by doing so - you are hiding the bug, you are not actually fixing it!

P.S. It might be counter-intuitive to some, but if you want to fix a memory bug - you need to enable the "Catch memory leaks" option (make sure the "Active only when running under debugger" option is off if you are running the app outside of the debugger). Enabling memory leaks checks allows EurekaLog to allocate additional memory blocks with information about allocated memory. In these additional memory blocks, EurekaLog can store, among other things, additional call stacks and information about the memory's data type. All this additional information can help EurekaLog produce more accurate diagnostic information if a problem was found.

P.P.S. Read more stories like this one or read feedback from our customers.

EurekaLog 7.11 is out

2022-12-01T09:57:00.003+00:00

We are pleased to announce the availability of the new 7.11 version.

EurekaLog is a tool for Delphi and C++Builder that gives your application the power to catch every exception and memory/resource leak, generating a detailed log of the call stack (with unit, procedure and line number), optionally sending you a copy of each log entry via email or the Web via the most used Web Bug-Tracking tools (as Mantis, BugZilla, FogBugz, JIRA, YouTrack, Redmine, Exceptionless, GitLab, and GitHub).

EurekaLog represents the most advanced exception and memory leaks logger technology available for Delphi/C++Builder developers.

To learn more about EurekaLog, please visit our website at:
https://www.eurekalog.com

To download a demo, please visit:
https://www.eurekalog.com/downloads.php

If you would like to purchase a new license, please visit:
https://www.eurekalog.com/buy.php

Changes in 7.11 build:

Added: Support for RAD Studio 11.2 (update 2 for 11 Alexandria)
Added: EurekaLog can now be packaged into a custom BPL package. Options from BPL package will be used to initialize EurekaLog. EurekaLogCore continues to be a default RTL package, which will use options from main executable
Added: [C++ Builder] Support for CLang/LLVM objects for memory features. Do not forget to update your EMemLeaksBCB.cpp files from EurekaLog installation folder
Added: [C++ Builder] Support for memory features for 64-bits
Added: [C++ Builder] New _TDSComplete option can now be used to turn off TDS processing for faster post-processing of C++ Builder projects (no line numbers will be added), good for quick testing, not recommended for production
Added: Stay On Top checkbox for MessageBox dialog
Added: New .LastSystemErrorCode property for exception info
Added: [Viewer] EurekaLog report version is now displayed as the first value under "General" tab
Added: A warning about saving your project before editing EurekaLog's options
Added: EurekaLog options will now have an unique GUID set
Added: Ability to add debug information/options to an external file (.edbg) instead of injecting inside executable. Can be used for C++ Builder when debugger is unable to recognize the modified .exe. Additionally, there is a hidden option DoNotTouchExe (for testing or packers/digital signatures)
Added: Ability to side-load external debug info for main module (for example, use EurekaLog options, but use JCL debug info)
Added: Made SMTPClientAdditionalHeaders to be additional argument for the EurekaLogSendEmail functions
Fixed: Custom/Help button will not be visible if no event handler is assigned
Fixed: [64-bit C++ Builder] IDE debugger crash when debugging EurekaLog-enabled executables
Fixed: [C++ Builder] Various memory diagnostic improvements
Fixed: [C++ Builder] Proper unit handling in IDE when switching target platform
Fixed: Added workaround for this issue
Fixed: Added support latest changes in JIRA API
Fixed: Taking screenshots from non-DPI awared applications
Fixed: [x64] Rare crash when following error line from report in IDE
Fixed: [Regression] MS Debug Info provider may fail to obtain information
Fixed: [Regression] Showing EurekaLog dialog may hung when parent window is not responding
Fixed: [Regression] Rare deadlock on startup when using MS Debug Info provider
Fixed: [Regression] ECC32 may fail to compile project when no .dproj/.cbproj file is specified
Fixed: Improved support for non-default output file extensions
Fixed: Freeze detection restart controls improvements
Fixed: EurekaLog style dialog will property set a default button
Fixed: Sometimes EurekaLog dialog could appear behind app's window
Fixed: Rare range-check error in exception dialogs
Fixed: Rare crash on startup of RAD Studio 11 Alexandria (bug in the workaround for the RSP-36484)
Fixed: [Regression] SMTP send speed improvements
Fixed: [C++ Builder] Incorrect unit initialization order could cause EurekaLog to ignore exceptions
Fixed: [C++ Builder] Installation of library paths for 64-bit
Fixed: [C++ Builder] Crash on startup in C++ Builder 2010 only
Fixed: Minor internal logging improvements
Fixed: Rare issues with some SMTP servers
Fixed: "Include child classes" option did not work correctly in some cases (mostly on older IDEs)
Fixed: OnExceptionNotify now works for leaks too
Fixed: Various minor improvements
Removed: Hook for CreateFileA function as no longer used by EurekaLog's run-time code. Now this hook is used only for design-time
Removed: The "Delete service files after compilation" option. You can add the "del "%_IDEDst%*.map";del "%_IDEDst%*.drc";del "%_IDEDst%*.dcu"" command (without external quotes) to EurekaLog's post-build event.
Changed: FastMM support units will no longer include debug information providers. You are supposed to manually add/enable providers that you want/need/use.
Changed: [IDE] New code for EurekaLog version update checks

Black Friday and Cyber Monday Sale

2022-11-21T05:00:00.001+00:00

We are pleased to announce Black Friday and Cyber Monday 30% discount on any of our EurekaLog products using the coupon code found below.

The sale starts on Black Friday (November, 25) and ends at the end of Cyber Monday (November, 28).

Enter this code when paying for the item on our web site:

BFCM2022

New customers (without existing licenses) can use the discount code here:

https://www.eurekalog.com/buy.php

Minimum supported client	Windows 95
Headers	Winuser.h
Library	User32.dll

EurekaLog's blog

Logging additional exception information

What this article is about

Logging additional exception properties

Customization

Using EExtraExceptionInfo with your own callbacks

Implemenation details

EurekaLog 7.15 is out

EurekaLog 25% Christmas Sale + 3 Months Extra of Maintenance Period

We're excited to announce a special EurekaLog Christmas sale!

Black Friday and Cyber Monday Sale

Managing local bug reports by bug reports file rotation

Why you may want a bug reports file rotation

Bug reports are not log entries

Managing size of bug report files

Removing obsolete bug reports

Using variables to rotate the local bug report file

Using events to rotate local bug report file

Performing the actual rotation

Introducing VirtualMM debugging memory manager

Contents

Memory architecture in Delphi applications

How do Delphi applications allocate memory?

How does System allocate memory?

What is a memory manager?

Why do Delphi applications use a memory manager?

What is the problem with a memory manager?

How do you find memory bugs in Delphi applications?

Write after delete

Buffer overflow

Calling methods of a deleted object

Calling a static method of a deleted object

Calling a virtual method of a deleted object

Read after delete

Memory reuse

What is the VirtualMM debugging memory manager?

Where can I download VirtualMM?

How to install VirtualMM?

How do I add (connect) VirtualMM to a project?

How to configure VirtualMM?

What problems does VirtualMM solve?

Referencing already freed memory

Buffer overflow

If the USE_SMALL_BLOCKS option is disabled

If the USE_SMALL_BLOCKS option is enabled

Calling a static method of a deleted object

Calling a dynamic method of a deleted object

Memory reuse

When should you use VirtualMM?

When NOT to use VirtualMM?

Using VirtualMM with EurekaLog

What should I do if my app crashes with out-of-memory errors when using VirtualMM?

Notes

EurekaLog 7.14 is out

EurekaLog and Windows Service Applications

How to read bug reports

Using EurekaLog with FastMM's full debug mode

EurekaLog-enabled application starts up x2 times slower on Windows 2016

"Invalid EurekaLog configuration found" error

What this check is

What the problem is

Solutions

"Pure DLL"

"Delphi DLL"

"Application DLL"

Legacy applications

Conclusion

Using EurekaLog with GMail (Google Mail) after May 1, 2025 and after May 14, 2025

Disable visual error dialogs for background apps

Test code

Apps with EurekaLog

Disabling system reports

Disabling only visual dialogs

Disabling dialogs in EurekaLog

Mixed mode apps or exceptions

Black Friday and Cyber Monday Sale

The Secret of Access Denied

Beware of secondary exceptions

Black Friday and Cyber Monday Sale

EurekaLog 7.12 is out

If the `USE_SMALL_BLOCKS` option is disabled

If the `USE_SMALL_BLOCKS` option is enabled

How to use `safecall` correctly