include memory.a or include ucrlib.aThe memory.a include file exports several symbols. The UCR Standard Library prefaces all "private" names with a dollar sign ("$"). You should not call any routine in this package that begins with this symbol. To avoid name conflicts, you should not define any symbols in your programs that begin with a dollar sign ("$"). Note that future versions of the stdlib (that remain compatible with this release) may change "private" names. To remain compatible with future releases, you must not refer to these "private" names within your programs unless otherwise directed.
Source code appearing in this chapter is current as of Version Two, Release 40. There may be minor changes between this source code and the current release.
A typical application program (that uses dynamic memory allocation) calls three different subroutines: MemInit, Malloc, and Free. The MemInit routine initializes the memory management system. You must call this routine (or the MemInit2 routine) before using any memory management routines or other routines that call memory management routines. Since a large percentage of programs utilize the memory management facilities in the standard library, the SHELL.ASM skeleton file already contains a call to MemInit for you. After the memory management system is initialized, you can begin making calls to malloc and free to allocate and deallocate blocks of memory.
The stdlib memory management routines maintain a reference count on every allocated block. By using the DupPtr routine, you can tell the stdlib that you have two (or more) pointers pointing at the same block in the heap. You must call Free once for each pointer you've duplicated in your system (i.e., you must call Free "reference count" times). Free decrements the reference count by one and only returns the memory to the free list if the reference count hits zero. By making a call to DupPtr for every copy of a pointer you make, you can avoid the "dangling pointer" problem in your code.
The stdlib contains many other utility routines that let you see how much memory is currently available, check the size of the largest available block, and check the status of some pointer you're currently using. See the following descriptions for more details.
zzzzzzseg segment para public 'zzzzzz' LastBytes byte 16 dup (?) zzzzzzseg endsTypically, you would only call MemInit once in a program. If you make more than a single call to MemInit, all variables allocated on the heap prior to the second call are effectively deallocated.
If you want finer control over the position and size of the heap in memory, see the MemInit2 routine. That routine lets you specify these values as parameters.
MemInit
dseg segment para public 'DATA'
<normal variable declarations>
align 16
Heap byte 32768 dup (?)
dseg ends
.
.
.
mov ax, offset Heap
shr ax, 4 ;Convert to a paragraph
add ax, seg dseg ; address.
mov es, ax
mov cx, 32768/16 ;# of paragraphs in the heap.
MemInit2
If the memory allocation request fails because there isn't a large enough block on the heap, the Malloc routine will check to see if the exception handling package is enabled. If this is the case, Malloc will raise the $InsuffMem exception. If the exceptions package is not active, Malloc returns with the carry set (conversely, Malloc always returns with the carry flag clear if it was able to satisfy the memory allocation request). To prevent Malloc from raising an exception, you can always (temporarily) disable the exceptions with a call to DisableExcept.
Because the current memory manager requires a certain amount of overhead data to keep track of blocks it allocates, and because it supports only paragraph granularity, Malloc will actually allocate more data than you request. As of version two, release 40, each block you malloc requires eight bytes of overhead and the total allocation (overhead plus requested size) must be an even multiple of 16 bytes. If you request only one byte, malloc will actually allocate 16 bytes on the heap. Likewise, if you request nine bytes, Malloc will actually allocate 32 bytes (eight bytes of overhead plus nine bytes of data is 17 bytes, Malloc always rounds up to the next even multiple of 16 bytes). This loss of available memory is known as internal fragmentation.
Malloc also suffers from another problem that may waste memory known as external fragmentation.. Whenever you call Malloc, it chooses an appropriate block of memory from a list of free blocks. It may turn out that there is sufficient free memory on the heap (if you add up the sizes of all the free blocks) but there is no single block large enough to fill the request. Since Malloc cannot rearrange other blocks in memory, it will fail to satisfy the request even though, technically, suffient free memory exists. To avoid external fragmentation you should avoid sequences of Malloc operations with random Free calls intermixed. If you Malloc blocks that are likely to be Free'd together, you will reduce the effects of external fragmentation.
MemPtr dword ?
.
.
.
mov cx, 256
malloc
jc MemAllocErr
mov word ptr MemPtr, DI
mov word ptr MemPtr+2, ES
.
.
.
Calling Free may not immediately make that block of memory available for future Malloc requests. Free decrements the reference counter associated with the current free block. If this counter is zero, then Free returns the block to the free memory list. If the count is not zero, then Free assumes some other pointer still references the block, so it does not deallocate the block.
There are several errors that can occur when you call Free. If Free successfully frees the memory block (or decrements the reference counter without incident), it returns with the carry flag clear. If it encounters an error, it will return with the carry flag set or raise a $BadPointer exception if exceptions are initialized and active.
There are two basic problems Free encounters. First, you attempt to free a block that Malloc did not allocate. This happens when you call Free and you don't pass it a pointer passed to you by Malloc. Another problem Free encounters is when you attempt to Free a block of memory that you've previously released to the system via a call to Free. Corruption of the heap will also cause problems with Free, but that usually falls into the second category above.
MemPtr dword ?
.
.
.
mov cx, 256
malloc
jc MemAllocErr
mov word ptr MemPtr, DI
mov word ptr MemPtr+2, ES
.
.
.
<use the memory pointed at by MemPtr>
.
.
.
les di, MemPtr
Free
jc FreeError
Like Malloc and Free, Realloc will return with the carry flag clear if the reallocation process is successful. If a failure occurs, Realloc will either raise an exception (if exceptions are active) or return with the carry flag set (if exceptions are not active). Failure can occur if there is insufficient memory to make the block larger or if you pass a bad pointer to the Realloc routine.
MemPtr dword ?
.
.
.
mov cx, 256
malloc
jc MemAllocErr
mov word ptr MemPtr, DI
mov word ptr MemPtr+2, ES
.
.
.
<use the memory pointed at by MemPtr>
.
.
.
; Now we need another 256 bytes:
les di, MemPtr
mov cx, 512
Realloc
jc MemAllocErr
.
.
.
<Use the 512 bytes available>
.
.
.
les di, MemPtr
Free
jc FreeError
DupPtr returns the carry flag clear if the pointer you pass has the same format that Malloc and Realloc returns. DupPtr does not actually check to see if this is legal, allocated, block of memory because of performance concerns. If you want to verify that the pointer is completely legal, call the IsPtr routine (see the example later). If DupPtr encounters an illegal pointer, it will return the carry flag set if exceptions are not active, it will raise a $BadPointer exception if they are active.
mov cx, BufferSize
malloc
mov word ptr BufPtr, di
mov word ptr BufPtr+2, es
DupPtr
mov word ptr BufPtrToo, di
mov word ptr BufPtrToo+2, es
.
.
.
On occasion, you might actually want to check the validity of the block as well as the pointer during a DupPtr operation. The following procedure shows how to accomplish this:
DupPtrChk proc
IsPtr
jc BadPointer
DupPtr
BadPointer: ret
DupPtrChk endp
DupPtrChk proc
IsPtr
jc BadPointer
DupPtr
ret
BadPointer: mov ax, $BadPointer
Raise
DupPtrChk endp
les di, MemPtr
IsInHeap
jc SkipOperation
DupPtr
SkipOperation:
IsPtr may run somewhat slowly because it has to compare the value in ES:DI against the starting address of possibly every allocated block on the heap. To do this, it has to do a linear search of the allocated blocks. Once it finds the block, it also has to check its reference count to make sure this value is greater than zero.
ChkIsPtr proc
IsPtr
jc RaiseExcept
ret
RaiseExcept: mov ax, $BadPointer
raise
ChkIsPtr endp
mov ah, 62h ;Get the current
int 21h ; program's PSP address.
mov es, bx
HeapStart
sub ax, bx ;Compute size of program
add ax, 2 ;Just to be save, add 32 bytes.
mov bx, ax
mov ah, 4ah ;DOS memory resize call.
int 21h
; Now the heap is free memory as far as DOS is concerned.
Note that the value that BlockSize returns may be slightly larger than the original allocation size because of internal fragmentation. In theory, you can safely use all the bytes that CX says are available. Keep in mind, however, that other sections of code may respect the original allocation size and never reference any bytes beyond the specified allocation size.
les di, MemPtr
BlockSize
push cx
malloc
pop cx
mov word ptr MemPtr2, di
mov word ptr MemPtr2+2, es
lds si, MemPtr
cld
rep movsb
MemAvail
cmp cx, 100h ;Largest block is not
jae AtLeast16K ; at least 16K long?
print "Warning, you are getting low on memory.",nl
AtLeast16K:
MemFree
cmp cx, 1000h ;Is there at least
jae AtLeast64K ; 64K available?
print "Warning, you are getting low on memory.",nl
AtLeast64K:
mov cx, 128
malloc
mov cx, 128
RdLp: getc
mov es:[di], al
inc di
cmp al, cr
loopne RdLp
BasePtr ;Restore ptr to beginning of str.
Puts ;Print the string.