memory.txt

汇编编程艺术

Include:               stdlib.a or memory.a


Routine:  Free
--------------

Category:               Memory Management Routine

Registers on Entry:     ES:DI - pointer to block to deallocate

Registers on return:    None

Flags affected:         Carry = 0 if no error.
			Carry = 1 if ES:DI doesn't point at a Free block.

Example of Usage:
			les     di, HeapPtr
			Free

Description:  Free (possibly) deallocates storage allocated on the heap by
	      malloc or Realloc.  Free returns this storage to heap so other
	      code can reuse it later.  Note, however, that Free doesn't
	      always return storage to the heap.  The memory manager data
	      structure keeps track of the number of pointers currently
	      pointing at a block on the heap (see DupPtr, below).  If you've
	      set up several pointers such that they point at the same block,
	      Free will not deallocate the storage until you've freed all of
	      the pointers which point at the block.

	      Free usually returns an error code (carry flag = 1) if you
	      attempt to Free a block which is not currently allocated or if
	      you pass it a memory address which was not returned by malloc
	      (or Realloc).  By no means is this routine totally robust.
	      If you start calling free with arbitrary pointers in es:di
	      (which happen to be pointing into the heap) it is possible,
	      under certain circumstances, to confuse Free and it will attempt
	      to free a block it really should not.

	      This problem could be solved by adding a large amount of extra
	      code to the free routine, but it would slow it down considerably.
	      Therefore, a little safety has been sacrificed for a lot of
	      speed.  Just make sure your code is correct and everything will
	      be fine!


Include:               stdlib.a or memory.a


Routine:  DupPtr
----------------

Category:             Memory Manager Routine

Registers on Entry:   ES:DI - pointer to block

Registers on return:  None

Flags affected:       Carry = 0 if no error.
		      Carry = 1 if es:di doesn't point at a free block.

Example of Usage:
		      les     di,  Ptr
		      DupPtr


Description:  DupPtr increments the pointer count for the block at the
	      specifiied address.  Malloc sets this counter to one.  Free
	      decrements it by one.  If free decrements the value and it
	      becomes zero, free will release the storage to the heap for
	      other use.  By using DupPtr you can tell the memory manager
	      that you have several pointers pointing  at the same block
	      and that it shouldn't deallocate the storage until you free
	      all of those pointers.


Include:              stdlib.a or memory.a


Routine:  IsInHeap
------------------

Category:             Memory Management Routine

Registers on Entry:   ES:DI - pointer to a block

Registers on return:  None

Flags affected:       Carry = 0 if ES:DI is a valid pointer.
		      Carry = 1 if not.

Example of Usage:
			les	di, MemPtr
			IsInHeap
			jc	NotInHeap

Description:  This routine lets you know if es:di contains the address of
	      a byte in the heap somewhere.  It does not tell you if es:di
	      contains a valid pointer returned by malloc (see IsPtr, below).
	      For example, if es:di contains the address of some particular
	      element of an array (not necessarily the first element)
	      allocated on the heap, IsInHeap will return with the carry clear
	      denoting that the es:di points somewhere in the heap.  Keep in
	      mind that calling this routine does not validate the pointer;
	      it could be pointing at a byte which is part of the memory
	      manager data structure rather than at actual data (since the
	      memory manager maintains that informatnion within the
	      bounds of the heap). This routine is mainly useful for seeing
	      if something is allocated on the heap as opposed to somewhere
	      else (like your code, data, or stack segment).


Include:              stdlib.a or memory.a

Routine:  IsPtr
---------------

Category:               Memory Management Routine

Registers on Entry:     ES:DI - pointer to block

Registers on return:    None

Flags affected:         Carry = 0 if es:di is a valid pointer.
			Carry = 1 if not.

Example of Usage:
			les	di, MemPtr
			IsPtr
			jc	NotAPtr



Description:  IsPtr is much more specific than IsInHeap.  This routine returns
	      the carry flag clear if and only if es:di contains the address
	      of a properly allocated (and currently allocated) block on the
	      heap.  This pointer must be a value returned by Malloc, Realloc,
	      or DupPtr and that block must be currently allocated for IsPtr
	      to return the carry flag clear.


Include:                stdlib.a or memory.a

Routine:  BlockSize
-------------------

Category:               Memory Management Routine

Registers on Entry:     ES:DI - pointer to block

Registers on return:    CX-	Size of specifed block (in bytes). Returns
				zero if ES:DI does not point at a legal block.

Flags affected:		None

Example of Usage:
			les	di, MemPtr
			BlockSize



Description:

BlockSize returns the size (in bytes) of a block allocated on the heap.
If the block is not in the heap, this code returns zero in CX.
This routine does NOT verify that the block was actually allocated and
is still allocated.  It just makes sure that the pointer points at a valid
location somewhere in the heap and returns the block size from the data
structure at the specified address.  You are responsible for ensuring that
you do not use a deallocated memory block.

Include:                stdlib.a or memory.a

Routine:  MemAvail
------------------

Category:               Memory Management Routine

Registers on Entry:     None

Registers on return:    CX-	Size of largest free block on the heap
Flags affected:		None

Example of Usage:
			MemAvail



Description:

MemAvail returns the size (in paragraphs) of the largest free block on the
heap.  You can use this call to determine if there is sufficient storage
for an object on the heap.

Include:                stdlib.a or memory.a

Routine:  MemFree
-----------------

Category:               Memory Management Routine

Registers on Entry:     None

Registers on return:    CX-	Size of all free blocks on the heap.
Flags affected:		None

Example of Usage:
			MemFree



Description:

MemFree returns the size (in paragraphs) of the the free storage on the
heap.  Note that this storage might be fragmented and not all of it may
be available for use by Malloc.  To determine the largest free block
available use MemAvail.

Include:                stdlib.a or memory.a