Saturn module basic concepts

Data types

The entire module uses one data type to refer to calculator objects: the SAT_OBJECT type. A SAT_OBJECT represents a Saturn (calculator) object of any type, which can be stored in any area of memory (TEMPOB, USEROB, or even the C-heap). The type SAT_OBJECT is in fact a form of nibble-aligned pointer, therefore pointer arithmetics work (with certain restrictions) but the usual C operators * and [] will not. This is hardly ever needed since there are high-level functions to perform most of the operations on Saturn objects.

Memory management

Calculator objects can be created in TEMPOB just like the calculator would normally do, but HPGCC can now also create Saturn objects in the C heap. Most functions can work with objects in any memory location in a completely transparent way. There is, however a small difference. Objects in TEMPOB are usually created, used and abandoned there until the next Garbage Collection (GC) is performed. Objects in the C heap need to be free'd when they are not needed anymore, just like any 'malloc'ed memory block in the heap. For this task, the Saturn module includes the function sat3_free(), which will free a memory block in the heap. sat3_free() will also physically free a TEMPOB object, so it is recommended that programmers use it for all objects, regardless of memory location. This will avoid memory leaks in the heap and at the same time it will keep TEMPOB clean, so no GC is needed.

One important aspect the programmer needs to consider is the monolithic nature of TEMPOB and USEROB. If an object is free'd in TEMPOB, or an object is PURGE'd from a directory in USEROB, or a new object is STOred, a large memory region is moved to 'close the gap'. The immediate consequence is that after STO, PURGE or sat3_free(), any SAT_OBJECT pointer may become invalid. It is the user's responsibility to keep track of these events, and discard his pointers every time one of the mentioned operations is performed. This doesn't affect objects created in the C heap, where memory blocks are never moved. In TEMPOB, only a GC or sat3_free() can move blocks of memory. In USEROB, creating, deleting or changing the name or size of any object or directory will cause pointers to become invalid. The effect is contained within the memory region being modified, so changes to USEROB will not invalidate pointers in TEMPOB and viceversa.

Next: Object creation and manipulation Prev: Saturn architecture overview