previous next top contents index framed top this page unframed
Figure 33–31. dispose (GENERIC)
| PROCEDURE dispose (MODIFIES REPEATABLE POINTER p); PROCEDURE dispose (MODIFIES REPEATABLE ARRAY a); PROCEDURE dispose (REPEATABLE MODULE m); PROCEDURE dispose (REPEATABLE STRING s); |
dispose frees the memory occupied by a dynamic record, data section, dynamic ARRAY, or MODULE so that the storage can be immediately reallocated for some other purpose. This freeing of memory is referred to as disposing the data structure that occupies the memory.
The POINTER form may be used to dispose a dynamic record, dynamic ARRAY, or data section; the ARRAY form disposes a dynamic ARRAY.
If p points to a data section, the FINAL PROCEDURE (if any) of the corresponding MODULE is executed before the memory is freed. If p points at the bound data section, it is unbound; i.e., the effect is the same as if unBind had been called for the MODULE.
If p points to an $area record, dispose issues an error message; use $disposeArea instead to dispose of an area.
The MODULE and STRING forms dispose all of the data sections of the MODULE m or the MODULE named by s. As with the POINTER form, the FINAL PROCEDURE of the MODULE is executed before the memory associated with each data section is freed. In addition, any runtime system data structures associated with the MODULE are disposed, and the control section of the MODULE is released; i.e., the association of the MODULE with the control section is broken, so that the next time the MODULE is bound or newed, the standard search PROCEDURE for MODULEs is followed.
A disposed record, data section, or ARRAY must not later be referenced. The argument to the POINTER and ARRAY forms is modified to Zero to prevent it from being used for future references. If there are other POINTERs to the disposed object (“dangling POINTERs”), the results of using them are undefined. Such a bug can be exceedingly difficult to track. A facility called “POINTER rigging” (see Chapter 6 of the MAINDEBUG User's Guide) can sometimes make it easier to track dangling POINTER bugs.
If p, a, or s is Zero, dispose does nothing.
The storage for any data sections, records, and ARRAYs that become inaccessible is eventually reclaimed by the garbage collector. Explicit use of dispose is a more efficient alternative, but may lead to bugs that are difficult to track if a POINTER to the disposed object is accidentally used.
MAINSAIL Language Manual, Section 33.30