GEOS Programming: 1.2 Basic Data Types and Structures: Handles and Pointers

1.1 Records and Enumerated Types | Next:

Handles and pointers are present everywhere in GEOS--they are the essential elements that make dynamic linking and efficient memory management possible.

GEOS pointers are all far pointers; that is, they are 32-bit addresses that reference specific locations in memory. They are normal C pointers and can be used as such. Two other pointer types are also used by GEOS: Object pointers (optrs) and segment pointers. Object pointers are described below; segment pointers are 16-bit addresses described in the Memory Management chapter.

Handles

Handles are 16-bit, unsigned values used for several purposes. They provide abstraction when the exact address of a data structure or other item is not known or is an inconsistent state. The kernel maintains a handle table to keep track of many of the handles in the system. Each entry in the handle table is 16 bytes that contains information about the item referenced by the handle; these 16 bytes are opaque to applications and libraries and can not be accessed or altered except by the kernel. Other handle types are managed in other tables by the kernel.

Handles are used for the following primary purposes. For a full description of how handles are used, see the Handles chapter.

Memory reference
Entries for memory handles contain pointers to memory blocks; when the blocks move, the pointers are updated. However, the handle's integrity is preserved, and applications keep track of just the handle value.
Virtual Memory reference
Entries for VM handles indirectly reference VM blocks similar to the way memory handles reference blocks of memory. VM handles may be used whether the VM block is resident in memory or not.
File and disk reference
Entries for file and disk handles contain information about the location and status of the referenced file/disk. They provide indirect access to files and disks in a manner similar to memory handles.
Data structure implementation
Certain frequently-used system data structures require a storage format that provides for quick and convenient access at all times. These data structures (for example, threads, event queues, messages, timers, and semaphores) are stored in Handle Table entries.
Optimization
The kernel will, if space permits, sometimes use Handle Table entries for optimized temporary storage. (For example, when passing parameters on the stack with messages, the kernel will occasionally use handles for storing the parameters.)

The NullHandle value (zero) is used to indicate a null handle.

There are over a dozen different types of handles that can be used by any sort of geode. These are listed in the GEOS Programming chapter. All are 16-bit unsigned integers.

Chunk Handles and Object Pointers

Objects and small data structures are stored in small memory pieces called chunks. Chunks are stored in memory blocks known as local memory heaps, and each local memory heap can contain several chunks. Each chunk is referenced by a combination of two handles: The MemHandle handle locates the local memory heap, and the ChunkHandle locates the chunk within the block. A null chunk handle value is specified by NullChunk .

Objects are referenced in the same way as chunks, but the handle and chunk handle are combined into a single structure called an Object Pointer, or optr. Each optr uniquely identifies a particular object in the system. Note that optrs are often used to reference non-object chunks and data structures. A null value is specified by NullOptr .

GEOS provides several macros, all defined in geos.h , for creating and parsing optrs.

ConstructOptr() This macro constructs an optr from a MemHandle and a ChunkHandle.
OptrToHandle() This macro extracts the MemHandle portion of the given optr.
OptrToChunk() This macro extracts the chunk handle portion of a given optr.

Pointers

Pointers can be used normally as in C. All Goc-generated pointers are far pointers; that is, they are 32-bits long, composed of a 16-bit segment and a 16-bit offset.

GEOS provides macros for extracting the segment and handle portions of pointers.

PtrToSegment() This macro returns the segment portion of the given pointer (returned as type "word").
PtrToOffset() This macro returns the offset portion of the given pointer (returned as type "word").

GEOS automatically loads code resources when needed. However, when you call routines through pointers, you must take special measures to see to it that the routine is properly loaded into memory. This is discussed below in Using Routine Pointers in Goc .

GEOS SDK TechDocs |

1.1 Records and Enumerated Types | Next:

1.3 Fixed Point Structures