Reclaiming GUIObject memory usage in Gen GUI applications
search cancel

Reclaiming GUIObject memory usage in Gen GUI applications

book

Article ID: 27738

calendar_today

Updated On:

Products

Gen Gen - Workstation Toolset

Issue/Introduction

In the effort to conform to the ActiveX model Gen tightened the sensitivity to correct GUIObject usage many releases ago:

  • Any attribute with domain type of GUIObject must be reset to null via the Action Diagram statement "SET <GUIObject> to NOTHING", regardless of how the object was acquired.
  • A GUIObject attribute is a pointer to reference counted memory, which must be cleaned up when it is no longer needed.


Typically in application logic a GUIObject attribute is used to temporarily reference various objects as required to interact with those objects:

  • It is possible for a GUIObject to contain a reference to an object even though that object no longer exists.
  • When application logic sets a GUIObject attribute to a new reference, any existing object referenced by that GUIObject is first released before being set to the new value.
  • When a GUIObject attribute contains an object reference and that object still exists and has not been destroyed, the GUIObject can successfully be set to a new value without first setting the GUIObject to NOTHING. However if that initial object no longer exists, the GUIObject must first be set to NOTHING otherwise when the new value is assigned the release of that non-existent reference will follow an invalid pointer to a destroyed object and cause a runtime error.


In older versions of Gen, imperfect management of those objects within the GUI Runtime allowed certain instances of this to work successfully. However these principles should now be followed:

  • Setting the GUIObject to NOTHING when its reference is no longer required before the object is destroyed (such as in a close window event) provides the correct release of the object and initialization of the GUIObject attribute. This is not an optional statement and is always required.
  • Failure to appropriately set a GUIObject to NOTHING before that object is destroyed can cause undesirable behavior, ranging from a very large memory leak to abnormal termination.
  • Similarly, setting a GUIObject to NOTHING after the object has been destroyed can also result in problems. Ultimately, the impact is that existing applications may have worked correctly in earlier releases but could now fail.

Environment

Gen 8.6 GUI C applications.

Resolution

In order to help users detect whether an abnormal termination is a result of a model inconsistency or a GUI Runtime issue, a diagnostic tool has been provided.

  • The tool provides the ability to run an application in a diagnostic mode to identify Action Diagram problems where a GUIObject attribute view is not correctly released using the SET <GUIObject> to NOTHING statement.
  • This diagnostics tool can be invoked by an environment variable setting and is ideally used in conjunction with the Diagram Trace Utility (DTU).
  • When executing under diagnostics mode, all add references, releases, and deletes of Gen OLE aware objects will be logged.
  • When a release of a GUIObject that has already been deleted has been requested (i.e. via a window close), an error dialog is presented.
  • The Error dialog describes the event and line number of the action diagram statement requesting the release, along with the event and line number of the action diagram statement that initially retrieved the GUIObject IDispatch value.

These and other details in the error message, along with tracing of the application, help identify what object and statements are causing problems.

The file GUIEnvironmentVariables.ini (directory "%Gen86%\Gen") may be used to enable the environment variable IEFTRACEGUIOBJECTS as follows:

  • IEFTRACEGUIOBJECTS=ERROR : provides the above error dialog.
  • IEFTRACEGUIOBJECTS=WARNING : provides additional warning dialogs when abuse is detected, but not yet fatal.
  • IEFTRACEGUIOBJECTS=LOG : provides a log recording each event. The output of this log requires executing the application within Microsoft Visual Studio, with the log written to the Debug window of Visual Studio. Execute the application as "devenv.exe loadmodulename.exe trancode" to start the application within Visual Studio.
  • IEFTRACEGUIOBJECTS=FIX : quietly suppresses potentially fatal "releases", before they become application failures.

Warnings:

  • This logging is expensive processing, but suitable for debugging an application by a user.
  • Executing with IEFTRACEGUIOBJECTS=FIX is not intended as a production solution to inadequate action diagram logic.
  • There is a significantly higher risk of out-of-memory failures and steady performance degradation if IEFTRACEGUIOBJECTS is set to any value in a production environment.

NOTE: If an error dialog is displayed that refers to the GUIObject view containing the IDispatch address of one of the following collection objects: CListColumnItem, CListItem, CListPermitted, CListRowItem, or CMenu; the dialog message error should be ignored and the option "NO" button should be selected.

Additional Information

Powered by Wolken Software