Article # 82, added by Geoworks, historical record
| first | previous | index | next | last |

Using the Swat heapspace command.




Some GEOS devices, like the Zoomer and OmniGo, use a
mechanism called the "transparent launch model." Under this
scheme, each application estimates its worst-case scenario
usage of memory or space in the global heap. When an
application is launched, it passes this value to the kernel.
If that amount of memory is not free, then other
applications are shut down in order to free up the required
amount.

Thus, IT IS IMPORTANT THAT EVERY APPLICATION RUNNING ON
THESE DEVICES SPECIFY A "HEAPSPACE" VALUE.

The heapspace value is calculated in the Swat debugger using
the "heapspace" command and declared in the *.GP file using
the "heapspace " entry. Without this number, your
application may adversely affect performance on the GEOS
device. If the number is too low, it can result in crashes
and/or data loss. If it's too high, fewer geodes will be
cached and system performance will suffer.

The "heapspace" command in Swat is a TCL script which
determines how much heapspace an application uses. Usage is:
"heapspace ." As of this writing, the current
version of this command does not give an accurate number. We
are fixing this problem; here is a workaround for the
meantime.

How to Measure Heapspace

The heapspace tool works by scanning the entire handle table
and tabulating information about block sizes. The size of
any memory block is stored in its handle entry in the handle
table. "heapspace " will add up the sizes of all
the blocks being used by  and any libraries
 depends on.

To use the tool, you must do the following:

- Finish coding and debugging your application and all
libraries it uses. Make sure you're really done: if future
revisions of your program require more memory, you will have
to compute the heapspace again.

- Run your application on the actual device. This will
result in more accurate numbers. You must connect to the
OmniGo or Zoomer with Swat to measure your application's
heapspace usage. Read the file \INSTALL\OMNIGO.TXT on the
CD-ROM for more information on debugging from an actual
OmniGo 100 device.

- In Swat, do "heapspace " at various points in
your application. Try it a few times when several UI objects
are onscreen, or when the application is doing anything that
requires lots of resources to be loaded into memory. Menus
aren't built out until they are first opened, so make sure
to open all the menus in turn before computing heapspace.

- Make the adjustments for system geodes detailed below.

- After taking many such measurements, when you begin to
feel confident that you have taken a measurement that really
reflects the maximum heap usage for your app, record the
value in your application's *.GP file. The two ways to do
this are in kbytes, e.g.:

    heapspace 13k

or in paragraphs, as in:

    heapspace 832

These are equivalent statements. If you don't specify a "k"
after the number, it is assumed to be expressed in
paragraphs. A paragraph is 16 bytes.

As you will see below, there are complicating factors on the
OmniGo that require some additional work to make heapspace
measurements.

The Problem & Solution

The main problem with the existing heapspace tool is its
failure to account for eXecute-In-Place (XIP) code
resources. These resources are executed directly from ROM,
and consequently don't need to be loaded into memory or
counted towards a geode's heapspace value.

The heapspace value for an application includes the values
for the libraries it uses. Certain libraries on each system
(OmniGo, Zoomer, PT-9000, etc.) are flagged as "system
geodes" and are counted in the sysReserve value stored in
the INI file. They don't need to be counted again when
adding up the application's values, since they're always
loaded.

The current version of the heapspace tool doesn't subtract
system geodes' heapspace values correctly for the OminGo,
because there are many more system geodes on OmniGo than
there were on previous platforms. The subtraction currently
needs to be done by hand.

System Geodes:
  ansic
  cardid
  cidfs
  color
  conview
  db
  fontman
  gadgets
  geos
  jedit
  jerror
  jkbd
  jlib
  jmotif
  jotter
  jpen
  jpwr
  jtable
  jutils
  jvideo
  key
  math
  ms4
  nimbus
  nonts
  notes
  palm
  pccom
  pcmcia
  pen
  rtcm
  ruler
  serial
  sound
  standard
  stream
  styles
  table
  text
  ucdriver
  vgfs
  vidmem
 
Basically, if you find any of these in the output from the
heapspace tool, subtract them from your total.

Conclusion

Every final, shipping product will need a "heapspace".
However, in order to calculate an accurate number, you need
to perform this step after most of your coding and debugging
is complete. By the time most of you reach this step, the
"heapspace" Swat command may be fixed, so check with
Geoworks developer support if you have not already received
or downloaded an update, or use the procedure outlined in
this article.