Specific APIs:spc
Specific APIs spc Memory API

Memory API Foundation

The functions described in the chapter on the memory API allow the C programmer to use Xbase++ memory management for data within a C function. The memory management of Xbase++ is not based on pointers (like the ANSI-C functions malloc/free), but on handles. Each memory object is clearly identified by its handle and the memory area where the data of the object has been put can only be determined using this handle. This indirection has various advantages:

-Since all references to memory objects are defined by their handles, the objects can be moved in memory to reduce fragmentation.

- Memory objects can be resized after generation (_momResize).

- Concurrent access to data from several threads is managed through the handles. It is guaranteed that only one thread can access a data object at one time.

- With this access management scheme, it is possible to run the garbage collector on a separate thread, independent of the rest of the application.

This mechanism does require more effort to access a memory object. Before data of an object can be read or changed, the pointer to the data must be requested via _momLock(). This fixes the position of the object in memory and prevents simultaneous access from other threads. As soon as access to the object is complete, the area must be released with _momUnlock().

All data from Xbase++ is put in memory objects, which means containers must also be locked before access. Handles from memory objects (momHandle) must not be confused with handles from containers (ContainerHandle). Accessing a momHandle with functions of the container API or manipulation of a container handle with memory functions will guarantee fatal results! Put another way, if the wrong type of handles are used with a particular API, there is no guarantee that an application will continue to run.

Remember that it is not required to use the memory API. If its use seems too complex at first, memory management of the operating system or from the C library can be used. Be aware, however, that if the memory API is not used, protecting memory from simultaneous access by multiple threads becomes the responsibility of the programmer (for example it may be handled by semaphores).

Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.