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.