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.

Fundamentals

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
• stack
• 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 be freed.

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 slower.

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 and constants.

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.

The Stack

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.

Final Thoughts

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.