Memory Management Using the Visual FoxPro API
The Visual FoxPro API provides direct access to the Visual FoxPro dynamic memory manager. API routines that request memory allocations return memory handles, which identify memory. The Visual FoxPro segment-loading architecture uses handles instead of pointers so it can manage memory more efficiently.
A memory handle is essentially an index in an array of pointers. The pointers point to blocks of memory that Visual FoxPro knows about. Nearly all references to memory in the API are made through handles instead of the more conventional C pointers.
Understanding Stacks
The control or library you create does not have its own memory stack. Instead, it uses the memory stack of its calling program, or in this case, the Visual FoxPro stack. However, you cannot control the size of the Visual FoxPro stack or affect the amount of stack space available to an ActiveX control or FLL.
Under normal circumstances, this distinction isn't important. The Visual FoxPro stack is generally large enough to hold the automatic variables you might need to allocate in a control or library. If you run out of stack space, you can always allocate additional memory on the heap dynamically.
Rules for Using Handles
The following rules apply to allocating and freeing memory handles:
Users must free all handles they allocate, including handles allocated by functions such as _Load().
_Load() only creates a handle when the variable you're loading is a character string (that is, ev_type = 'C'). All the other data types store their values in the Value structure itself, while loading a character string puts an MHANDLE in the ev_handle of the Value structure.
In an FLL library, Visual FoxPro assumes responsibility for freeing all handles returned with _RetVal( ). Users must not free these handles, even if they allocate them.
Users must not free handles passed to them in their ParamBlk.
Warning
When you write an external routine that calls functions, make sure to follow all rules and check the return results. A stray pointer or handle reference could damage the Visual FoxPro internal data structures, causing an immediate abnormal termination or delayed problems, which could result in data loss.