... and a cop pulled me over. And he said, "Hey, are
you small?" I said, "No, I'm tall, I'm tall." He said,
"Well, I'm gonna have to measure ya."
"Let's Get Small"
Dealing with Memory
So, you've whipped up another small Waba program. It runs fine on your
PC under a JVM and you package it up with warp and exegen to run it
on a PalmPilot or Windows CE device.
When you run it, you get a message saying the WabaVM is out of memory.
Is that it? Is the program to big for the device?
The answer is most likely no. This page should explain what's going on
and how to get things working.
Waba programs are executed by a Waba Virtual Machine.
A Waba program consists of classes (usually packaged
in a warp file) and a launch program.
Under PalmOS the launch program is a .prc and under Windows CE,
it is a .lnk (Windows shortcut) file. The job of the
launch program is to start the WabaVM and tell it where
the class files for the Waba program are. It also has
another important responsibility. It tells the WabaVM
how much memory to allocate for the program.
The "exegen" program is used to build launch programs and
it allows you to specify how much memory a WabaVM should allocate
for a program. If you don't specify anything, some
default values will be used. To see the default values, run
the exegen program with no parameters.
The WabaVM allocates 4 chunks of memory from the device it is running
on when it starts up. The launch program tells the WabaVM what size
these chunks are. The 4 chunks of memory are:
- object heap
- class heap
- native stack
The WabaVM only allocates memory from the device once, when the program
starts up. From them on, it performs memory management within the regions
it allocated. It frees the 4 chunks of memory when the program has completed.
Under PalmOS, the object heap, stack and native stack are allocated from
dynamic memory and the class heap is allocated from storage memory.
If the WabaVM can't allocate the 4 chunks of memory, it will generate
a "can't allocate memory" error. This is different from an "out of memory"
error. The "can't allocate" error means the WabaVM can't allocate the
amount of memory it has been told the program needs when it starts up.
An "out of memory" error message occurs while the program is executing.
It means that the WabaVM allocated the 4 chunks of memory for the program
when it started up but the program is requesting more memory than is
left in one of the chunks.
So, to remove "out of memory" errors, you can increase the size of the
chunk of memory that the program ran out of. If you get an "out of object heap"
error message, for instance, you can specify a larger object heap size
for the program when you use exegen to build the launch program.
This will cause the WabaVM to request a larger chunk of memory for the
object heap when it starts up. On devices with limited amounts of memory,
you have to be careful that you don't specify something too large or
the WabaVM won't be able to allocate the amount of memory requested.
Under a Palm Personal, for instance, the maximum object heap you are probably
going to want to specify is 8K. Under other Palm devices
(Palm Professional, Palm III, etc.) you can specify up to a 64K object
heap. Under Windows CE, you can specify basically any size but it's
still best to keep programs as small as possible even when the
memory is available.
So, we've explained that the WabaVM allocates 4 chunks of memory when it
starts up: object heap, class heap, stack and native stack. But what's
in the four chunks? Below we explain what each chunk of memory is
and how it is used.
The Object Heap
When a Waba program creates an object, the WabaVM looks for
some free memory in the "object heap" where it can put the object.
The object heap is where all objects are kept.
If an object is created and there is no space left in the object
heap for it, the WabaVM will garbage collect the object heap.
Garbage collection is the process of examining the heap to
determine which objects are in use and which objects can
If there is still no space for the object after the WabaVM
garbage collects the object heap, then the WabaVM will issue
a message saying the program is out of "object heap".
So, this is where "out of object heap" messages come from.
A simple way of fixing an "out of object heap" message is to
increase the size of the object heap.
The default object heap size is 8K. Why is it this small
by default? It's currently this value to maintain
support for the Palm Personal which has an very small
amount of dynamic memory.
On a Palm Professional, Palm III or Windows CE device, you can
use object heaps that are bigger than 8K but if you want your
program to run on a Palm Personal, you will need to keep
the object heap relatively small.
The amount of memory allocated to the object heap can affect the
performance of a program. If you allocate lots of memory
for the object heap, the program won't perform as many garbage
collections but the process of garbage collection will be a little
If you allocate too small of an object heap, either the program won't
run or it will perform lots of garbage collections as it tries to
free up space.
The object heap is the only heap where the amount of memory allocated
may have some affect on performance. Changing memory settings for
any of the other chunks will not affect performance in any way.
The Class Heap
When the WabaVM encounters a reference to a new class, it locates
the class (either in memory or on disk) and creates a small data
structure in memory. This data structure contains tables
that allow the WabaVM to quickly look up fields, methods
This data is kept in the class heap. The more classes your
program references, the more class heap it will use. The class
heap is not garbage collected.
Each time a Waba program calls a method, it pushes data onto
a stack. A program that has deeply nested method calls will require
a larger stack than one that does not.
Methods that are highly recursive can require a large amount of stack
space. The default size of a Waba program's stack is around 1K.
If a program runs out of stack space, it will get a "stack overflow"
error. If you encounter this error, you can increase the size of
the program's stack using exegen.
The Native Stack
The WabaVM contains another stack it uses internally. This is known
as the native stack. Its default size is around 300 bytes. You will
probably never need to increase its size, but
it is possible you might need to if you use large multi-dimensional arrays.
If you get a "native stack overflow" error, it means the program has run
out of native stack.
Memory management in Waba is a little trickier than other platforms.
It would be nice if the WabaVM automatically adjusted the size
of its heaps depending on what is available on the device and what
it estimates the program requires.
We may do this in a future release but in the meantime, you'll
probably need to do some memory parameter tuning in exegen.
The reason the WabaVM doesn't try to determine the sizes itself
in the current release is because it's not easy to
determine programmatically how much memory a program will
need or to adapt memory regions dynamically while a program
is running on a small device.
On large machines (desktops, servers), memory management is easier
since if you run out of a chunk of memory, you can just allocate a
larger one and copy the smaller one in.
But on a small device, when you are out of a chunk of memory, its
likely you won't have the space available to allocate another larger
chunk while holding on to the smaller chunk so it can be copied in.
So, we opted to allow programmers to determine the sizes of the heaps
since they have knowledge of what the program will require when it runs
before it actually starts executing.
Copyright (c) 1999 - 2001 Wabasoft. Waba, WabaVM and WabaSDK are trademarks of