Garbage collection and memory management
The PowerBuilder garbage collection mechanism checks memory automatically
for unreferenced and orphaned objects and removes any it finds, thus
taking care of most memory leaks. You can use garbage collection
to destroy objects instead of explicitly destroying them using the DESTROY statement.
This lets you avoid runtime errors that occur when you destroy an object
that was being used by another process or had been passed by reference to
a posted event or function.
A reference to an object is any variable whose value is the
object. When the variable goes out of scope, or when it is assigned
a different value, PowerBuilder removes a reference to the object
and counts the remaining references, and the garbage collection
process destroys the object if no references remain.
Garbage collection occurs:
- When the
garbage collection interval has been exceeded and the PowerBuilder
application becomes idle and - When you explicitly call the GarbageCollect function.
When PowerBuilder completes the execution of a system-triggered
event, it makes a garbage collection pass if the set interval between
garbage collection passes has been exceeded. The default interval
is 0.5 seconds. Note that this system-triggered garbage collection
pass only occurs when the PowerBuilder application is idle, therefore
if a long computation or process is in progress when the interval
is exceeded, garbage collection does not occur immediately.
You can force immediate garbage collection by invoking the GarbageCollect function.
When you use dot notation and OLEObjects, temporary variables are created.
These temporary variables are released only during the garbage collection
process. You might want to invoke GarbageCollect inside
a loop that appears to be causing memory leaks.
The garbage collection pass removes any objects and classes
that cannot be referenced, including those containing circular references
(otherwise unreferenced objects that reference each other).
Posting events and functions When you post an event or function and pass an object reference,
PowerBuilder adds an internal reference to the object to prevent
its memory from being reclaimed by the garbage collector between
the time of the post and the actual execution of the event or function.
This reference is removed when the event or function is executed.
Exceptions to garbage collection
There are a few objects that are prevented from being collected:
- Visual objects Any object that is visible on your screen is not collected because
when the object is created and displayed on your screen, an internal
reference is added to the object. When any visual object is closed, it
is explicitly destroyed. - Timing objects Any Timing object that is currently running is not collected
because the Start function for a Timing object
adds an internal reference. The Stop function
removes the reference. - Shared objects Registered shared objects are not collected because the SharedObjectRegister function
adds an internal reference. SharedObjectUnregister removes
the internal reference.
Controlling when garbage collection occurs
Garbage collection occurs automatically in
PowerBuilder, but you can use functions to force immediate garbage
collection or to change the interval between reference count checks.
Three functions let you control when garbage collection occurs: GarbageCollect, GarbageCollectGetTimeLimit,
and GarbageCollectSetTimeLimit.
For information about these functions, see
the PowerScript Reference
. For an example illustrating
their use, see the Code Examples sample application, described in Chapter 1, “Using
Sample Applications.”
Performance concerns
You can use tracing and profiling to examine the effect of
changing the garbage collection interval on performance.
For information about tracing and profiling,
see the PowerBuilder Users Guide
.
Configuring memory management
You can set the PB_POOL_THRESHOLD environment
variable to specify the threshold at which the PowerBuilder memory
manager switches to a different memory allocation strategy.
When most windows, DataWindows, DataStores, or other PowerBuilder objects
are destroyed or reclaimed by the garbage collector, the PowerBuilder heap
manager returns the memory allocated for each object to a global
memory pool and records its availability on a global free list.
The freed memory is not returned to the operating system. When a
new object is created, PowerBuilder allocates blocks of memory from
the global memory pool (if sufficient memory is available in the
global free list) or from the operating system (if it is not) to a
memory pool for the object.
When the memory required by an object exceeds 256KB, PowerBuilder
uses a different strategy. It allocates subsequent memory requirements
from the operating system in large blocks, and returns the physical
memory to the operating system when the object is destroyed. It
retains the virtual memory to reduce fragmentation of the virtual
address space.
For most applications and components, the threshold of 256KB
at which PowerBuilder switches to the “large blocks” strategy
works well and reduces the memory required by an application when
it is working at its peak level of activity. However, if you want
to keep the overall physical memory usage of your application as
low as possible, you can try setting a lower threshold.
The advantage of setting a low threshold is that the size
of the global memory pool is reduced. The application does not retain
a lot of memory when it is inactive. The disadvantage is that large
blocks of memory are allocated for objects that require more memory
than the threshold value, so that when the application is running
at its peak of activity, it might use more virtual memory than it
would with the default threshold.
Setting a low threshold can be beneficial for long-running
client applications that use many short-lived objects, where the
client application’s memory usage varies from low (when
idle) to high (when active). For multithreaded applications, such
as servers, a higher threshold usually results in lower virtual memory
utilization.
Logging heap manager output
You can record diagnostic ouput from the PowerBuilder heap
manager in a file to help you troubleshoot memory allocation issues
in your application. The PB_HEAP_LOGFILENAME environment
variable specifies the name and location of the file.
If you specify a file name but not a directory, the file is
saved in the same directory as the PowerBuilder executable, or,
for a PowerBuilder component running on EAServer,
to the EAServer bin directory.
If you specify a directory that does not exist, the file is
not created, or, for a PowerBuilder component running on EAServer, output is written to the EAServer log file (Jaguar.log).
By default, the log file is overwritten when you restart PowerBuilder
or EAServer. If you want diagnostic
output to be appended to the file, set PB_HEAP_LOGFILE_OVERWRITE
to false.
You can set the variables in a batch file that launches the
application, or as system or user environment variables on the computer
or server on which the application or component runs.
For more information about tuning memory management in PowerBuilder
and EAServer, see the technical
document EAServer/PowerBuilder Memory Tuning and Troubleshooting
.