GEOS SDK TechDocs
|
| 
1.8 Geode Protocols and Release Levels
| 
2 Creating Icons
GeodePrivAlloc(), GeodePrivFree(), GeodePrivWrite(), GeodePrivRead()
Every geode in the system has a "private data" area, a space set aside in its core block. This private data is used primarily by library geodes, when each of the library's clients uses its own copy of a particular data structure that gets manipulated by the library. The private data mechanism is used in the GEOS implementation of
malloc()
, for example (though you need not know this to use
malloc()
).
Private memory may be allocated, written to, read from, and freed by the library. The library does not have to allocate a block for each geode and maintain its own handle table; the use of the
GeodePriv...()
routines automatically manages this.
GeodePrivAlloc()
reserves a given number of contiguous words for the library within the private data of all geodes in the system. The memory space is reserved but is not actually allocated for a given geode until it is used (written to); this is done for optimization purposes. This routine will return a tag pointing to where the reserved words begin. This tag is used when reading, writing, or freeing the private data. If the memory could not be allocated, the routine will return zero.
GeodePrivWrite()
and
GeodePrivRead()
write to and read from the private data space. They take similar parameters: a geode handle, the tag as returned by
GeodePrivAlloc()
, the total number of words to be written or read, and a pointer to a locked or fixed buffer. In
GeodePrivWrite()
, the buffer will be passed containing the words to be written; in
GeodePrivRead()
, the buffer will be passed empty and returned containing the words read.
Typically, the geode handle passed will be zero; this indicates that the current process (which will be the library's current client) will be the owner of the private data affected. Because the library code will be executing in the thread of a given application, the application geode will be the only one having its private data affected. Thus, a library can use the same code to store different data for each geode that uses it; neither the library nor the geode needs to know that other geodes are also using the same routines.
GeodePrivFree()
frees a given number of words from all geodes' private data. It needs to be passed only the number of words to be freed and the tag as returned by
GeodePrivAlloc()
.
GEOS SDK TechDocs
|
| 1.8 Geode Protocols and Release Levels
| 2 Creating Icons