heapinfo.txt

一个堆栈管理器的源码

      _heapchk/set/walk() family of functions, and also tested by
      the debugger when _HEAPDEBUG or _HEAPTRACE are defined.

      Read-only heap entries may be modified, and their read-only
      status preserved by re-invoking _heapwatch() on the affected
      heap entry. 


V. Compatibility with MSC -- only 99.44%

   The replacement heap manager is as close as possible to full
   compatibility with the original MSC heap manager, but, inevitably,
   there are a few differences.


   A. STDMSC

      The symbol STDMSC is available if strict source-code compatibility
      with MSC is required.  Applications compiled with -DSTDMSC are
      guaranteed to compile with MSC's malloc.h instead of heap.h.


   B. Compromises

      Functionally, the replacement heap manager was to be identical
      to the original MSC heap manager, but a few compromises intervened.


      1. The replacement heap manager is not limited to allocations
         of 65516 bytes or less.  It will supply "far" blocks up to
         65535 (actually 65536) bytes and "huge" blocksof unlimited
         size.  The MSC restriction of 65516 bytes apparently derives
         from MSC's lack of support for large pointers.  It uses 16-bit
         operations on 32-bit pointers, which means that a region based
         at 1234:000E can only extend to 1234:FFFF.  Thus it loses up
         to 14 bytes due to lack of paragraph alignment.  Another six
         bytes is lost to the heap control block associated with each
         heap entry.

         The replacement heap manager uses paragraph alignment and does
         not count its heap control blocks against the segment limit.
         Thus it is able to  deliver a full segment of 64 Kb.  (See 
         SIZE_MAX described in section III.B.1).


      2. The replacement heap manager is larger than the equivalent
         MSC routines. The difference is several KB depending on which
         functions are used.


   C. Address models

      The replacement heap manager handles the "far" heap.  The "near"
      heap is handled by the standard MSC heap manager.  In "small"
      and "medium" programs, which use "near" as the default data
      address model, the functions calloc(), free(), malloc(), _msize(),
      and realloc() use the "near" heap and are not superceeded by the
      replacement heap library. In "compact", "large", and "huge"
      programs, which use "far" as the default data address model,
      the functions calloc(), free(), malloc(), and realloc() use the
      "far" heap and are superceeded by the replacement heap library.

      The replacement heap manager supports pointer checking, debugging,
      and tracing for "far" heap access only.  Thus calloc(), free(),
      malloc(), and realloc() cannot be debugged in "near" data model
      programs.  The model-specific heap access functions, which have
      an '_f' prefix, are available at all times and so are their
      alternate functions for pointer checking, debugging, and tracing.

      Note that in "far" address model programs the replacement heap
      manager automatically recovers unused space from the "near" heap
      when the "far" heap is first accessed.  This process is described
      in section II.B.


VI. Distribution files


   A. Library source files:

      CALLOC   C   - calloc() replacement
      CALLOC_D C   - calloc() with debugging
      CALLOC_T C   - calloc() with tracing

      ERRCHK   C   - debugging utility routines

      EXPAND   C   - _expand() replacement
      EXPAND_C C   - _expand() with pointer checks
      EXPAND_D C   - _expand() with debugging
      EXPAND_T C   - _expand() with tracing

      FHEAPCHK C   - _fheapchk/set()  replacement

      FHEAPDMP C   - dumps heap state to a file

      FHEAPPCK C   - releases excess heap memory to DOS
      FHEAPK_D C   - _fheappack() with debugging
      FHEAPK_T C   - _fheappack() with tracing

      FHEAPWAL C   - _fheapwalk() replacement

      FHEAPWAT C   - watches heap entries for damage

      FMALLOC  C   - _ffree() & _fmalloc()
      FMALL_C  C   - _ffree() & _fmalloc() with debugging
      FMALL_D  C   - _ffree() & _fmalloc() with debugging
      FMALL_T  C   - _ffree() & _fmalloc() with tracing

      FMSIZE   C   - _fmsize() replacement
      FMSIZE_C C   - _fmsize() with pointer checks

      FREE     ASM - free() replacement [maps to _ffree() or _nfree()]
      FREE_C   ASM - free() with pointer checks
      FREE_D   ASM - free() with debugging
      FREE_T   ASM - free() with tracing

      FREECT   ASM - _freect(), _memavl(), and _memmax() replacements

      FRELOC   C   - moves a heap entry as low as possible in memory
      FRELOC_C C   - _frelocate() with pointer checks
      FRELOC_D C   - _frelocate() with debugging
      FRELOC_T C   - _frelocate() with tracing

      HALLOC   C   - halloc() & hfree() replacement
      HALLOC_C C   - halloc() & hfree() with pointer checking
      HALLOC_D C   - halloc() & hfree() with debugging
      HALLOC_T C   - halloc() & hfree() with tracing

      HEAP     H   - header file for applications using this heap manager

      HEAP     I   - internal header file for library routines

      HEAPSTAT C   - translates status codes to text strings

      HEAPUTIL C   - heap management utility routines

      HEXPAND  C   - _expand() for huge blocks
      HEXPAN_C C   - _hexpand() with pointer checks
      HEXPAN_D C   - _hexpand() with debugging
      HEXPAN_T C   - _hexpand() with tracing

      HMEMCMP  C   - memcmp() for huge blocks
      HMEMCPY  C   - memcpy() for huge blocks
      HMEMSET  C   - memset() for huge blocks
      HMEMSUM  C   - memsum() for huge blocks - for debugging with _fheapwatch()

      HREALLOC C   - realloc() for huge blocks
      HREALL_C C   - hrealloc() for with pointer checks
      HREALL_D C   - hrealloc() with debugging
      HREALL_T C   - hrealloc() with tracing

      HMSIZE   C   - _msize for huge blocks
      HMSIZE_C C   - _hmsize() with pointer checks

      MACRO    INC - include file ASM files

      NHEAPCHK ASM - _nheapchk() & _nheapset() replacements

      NHEAPWAL ASM - _nheapwal() replacement

      NMALLOC  ASM - _nfree() & _nmalloc() replacements

      NMSIZE   ASM - _nmsize() replacement

      PTRCHK   C   - checks for and reports invalid pointers

      REALLOC  C   - realloc() replacement
      REALL_C  C   - realloc() with pointer checks
      REALL_D  C   - realloc() with debugging
      REALL_T  C   - realloc() with tracing

      XHEAPCHK ASM - maps _heapchk/set/walk() to "near" and "far" variants


   B. Ancillary files

      BUILD    BAT - activates the make file to create libary and test programs

      MAKEFILE     - make script file (matches CompuServe/MSSYS/DL3/NDMAKE.ARC)


   C. Demonstration program source files

      These files are not part of the heap manager, but demonstrate
      some of its properties.

      BENCH    C   - benchmark/exercise harness for heap manager

      DBUGDEMO C   - example of heap debugger in action

      PACKDEMO C   - example of heap relocation and packing

      STDMSC   C   - program to exercise MSC heap routines for reference info



VII. Versions (in reverse order)


   4. Released 3-Mar-90.

      a. Bug fixes

         i. Hfree.asm was defining _hfree() rather than hfree.  The
            typo has been corrected.

         ii. _heapwalk() contained a bug related to multiple arenas
             that has been fixed.


      b. Changes

         i. _Fheapset() has a side effect of resetting the default fill
            value for the safety margins.

         ii. The heap manager ignores changes to _heappad after heap
             initialization.  It uses a snapshot taken at init time
             to avoid variation in the offset from the control structures
             to the application data regions.


      c. New features

         i. The function _heapstat() is available to convert _heapxxx()
            status codes to appropriate text strings.

         ii. The compiler switch -D_HEAPDEBUG=<stream> where <stream> is
             stdout, stderr, or an application error log file enables
             special debugging routines.  Functions that modify the
             heap first check the heap for errors.  They also record
             the transaction for later reference.  When an error is
             detected a diagnostic report is written to the idicated
             output file  For more information see section IV.D.

         iii. The compiler switch -D_HEAPTRACE=<stream> enables heap
              function tracing to the indicated stream file.  For
              more information see section IV.E.

         iv. Heap.h is now a proper replacement for malloc.h.  The library
             replaces the far heap in all address models (including "small"
             and "medium").


   3. Released 15-Feb-90


      a. Bug fixes

         i. _Heapwalk() is now fully MSC compatible.


      b. Changes

         i. _Relocate() can handle "huge" heap entries.  _Relocate()
            ignores  _heapmode and always positions the entry as low
            as possible in memory to maximize the effect of _heappack().

         ii. Both ends of the heap entries get safety margins _heappad
            bytes long.  The safety margins are automatically filled
            with a distinctive bit pattern (0x55) when the region is
            allocated.

         iii. Chunk headers are now adjacent to the data region.  This
            reduces the control overhead from 16 to 8 bytes per block,
            and removes the need for _HEAPALIGN variants.


      c. New features

         i. An alternate method of handling invalid pointers was added.
            Normally,the functions that accept pointer parameters check
            the pointers for validity and silently ignore erroneous
            invocations.  Applications compiled with -DPTRCHK use
            alternate functions which report errors on stderr.  The error
            reports include name of the offending function, the value of
            the invalid pointer, and the source file name and line number.


   2. With _HEAPALIGN set TRUE the unused area of the header paragraph
      provides an automatic front-end pad like _heappad provides for the
      other end of the chunk.  However, the length is fixed (6 bytes). 
      In version 2 _heapset() affects the front-end pad bytes for all
      chunks as well as the data areas of free chunks.

      The _fheapxxx() functions were jumping to heapxxx() rather than
      _heapxxx().  The typo has been corrected

      Halloc(), hfree(), and _hsize() are now supported.  The pointers
      from halloc() are compatible with the pointers from malloc().  This
      similarity removes one of the major problems of the MSC heap
      manager: pointer disposal.  In a mixed environment containing both
      far and huge heap entries, the MSC heap manager requires that the
      application program track the source of each entry so that the
      proper function may be used to dispose of the entry when processing
      is complete.  There is no such requirement with the replacement heap
      manager.  Free() will handle any heap pointer correctly.


   1. First release


VIII.  Licensing, distribution, and conditions of use


   A. This software and the associated documentation is copyright (c)
      1990 Optimal Sofware, All Rights Reserved.


   B. This software is provided as a service of Optimal Software.  There
      are no royalties or fees associated with its use.  You may
      distribute programs linked with this software without restriction.


   C. There is a restriction on the sale or distribution-for-profit of
      this software.  A written license from Optimal Software is required
      to sell the software in source or object (unlinked) form.

      No license is required if the software is distributed for free.
      However, the entire package must be copied, including this
      documentation.


   D. Naturally we are interested in suggestions and improvements.  If
      you have any please let us know.