1.3.14 Memory Management Functions

Under Windows 3.1, there are two forms of memory management calls, Local and Global. The Global memory manager allocates segments from physical memory and returns a handle value that can be converted into a far pointer using the GlobalLock function. Global memory is globally visible to all applications, either by explicit request or implicitly because that is the way Windows 3.1 is implemented with all processes running in the same address space. The Local memory manager allocates objects from within a 64KB segment and returns a 16-bit offset to the allocated memory.

Under Win32, the local and global memory manager function calls are kept relatively intact, with movable and discardable options supported along with the lock and unlock functions. The major difference is that local memory objects have a 32-bit handle instead of a 16-bit handle and the handle is an actual pointer instead of an offset relative to a segment. These changes will not affect most portable 16-bit code, which treated local memory handles as either char * or char **.

The other major difference between Win32 and 16-bit Windows is that global memory is no longer visible to all Windows applications. Since each application has its own address space, memory allocated by one process is not visible outside of the address space of that process. Memory used in DDE transactions will transparently be made available to the receiving process. Applications which need shared memory for other purposes should use named shared memory (available via CreateFileMapping).

Since the local and global memory manager function calls were designed specifically for a segmented environment and we did not want to change the function calls in any significant way, two new memory manager function sets have been added to the Win32 function set. The function calls are designed for use in a 32-bit linear address space. The Heap Manager function calls are analogous to the local memory manager, except that they operate on an explicit heap object instead of the heap object associated with the current process. This allows DLL code that used a private heap to be written for the Win32 environment. The Virtual Memory manager function calls are analogous to the global memory manager, except that they allow the sparse allocation of large contiguous objects.

For additional information on memory management, see the Memory Management overview.

The memory management functions include:

Function Description

GetFreeSpace Retrieves the number of bytes available in the global heap
GetFreeSystemResources Gets information about system memory. GlobalAlloc Allocates memory from the global heap
GlobalCompact Compacts global memory to generate free bytes
GlobalDiscard Discards a global memory block if the lock count is zero, but does not invalidate the handle of the memory block
GlobalFix Prevents a global memory block from moving in linear memory
GlobalFlags Returns the flags and lock count of a global memory block
GlobalFree Removes a global memory block and invalidates the handle of the memory block
GlobalHandle Retrieves the handle of a global memory object
GlobalLock Retrieves a pointer to a global memory block specified by a handle
GlobalLRUNewest Moves a global memory object to the newest least-recently-used (LRU) position
GlobalLRUOldest Moves a global memory object to the oldest least-recently-used (LRU) position
GlobalMemoryStatus Returns information on current availability of memory
GlobalNotify Installs a notification procedure for the current task
GlobalReAlloc Reallocates a global memory block
GlobalSize Returns the size (in bytes) of a global memory block
GlobalUnfix Unlocks a global memory block previously fixed by the GlobalFix function
GlobalUnlock Invalidates the pointer to a global memory block previously retrieved by the GlobalLock function
HeapAlloc Allocates memory from the specified heap
HeapCreate Creates a memory allocation heap
HeapDestroy Destroys a memory allocation heap
HeapFree Frees memory allocated from the specified heap
HeapSize Returns the size of the specified allocated object
LocalAlloc Allocates memory from the local heap
LocalCompact Compacts local memory
LocalDiscard Discards a local memory block if the lock count is zero, but does not invalidate the handle of the memory block
LocalFlags Returns the memory type of a local memory block
LocalFree Frees a local memory block from memory if the lock count is zero and invalidates the handle of the memory block
LocalHandle Retrieves the handle of a local memory object
LocalInit Initializes a local heap in the specified segment
LocalLock Locks a block of local memory by increasing its lock count
LocalNotify Installs a notification procedure for current task.
LocalReAlloc Reallocates a local memory block
LocalShrink Shrinks the local heap
LocalSize Returns the size (in bytes) of a local memory block
LocalUnlock Unlocks a local memory block
LockData Locks the current data segment in memory
UnLockData Unlocks the current data segment
VirtualAlloc Reserves and/or commits a region of the virtual address space
VirtualFree Releases and/or decommits a region of the virtual address space
VirtualProtect Changes the protection of a region of the virtual address space
VirtualQuery Returns information about a region of virtual address space