heap.man

一个堆栈管理器的源码

      There are three heaps involved in the run-time library.  The "near"
      heap uses the default data segment.  The "far" heap uses memory
      from the operating system.  The default heap is the same as one of
      the first two heaps.  It always matches the size of the default
      data addressing model.
      

      a. This list covers all of the memory allocation functions.  Functions
         unique to the replacement heap manager are mark with an '*'.


         alloca       Allocates memory from the stack

         calloc       Allocates memory for an array from the default heap

         _expand      Adjusts the size of an entry in the default heap

         _ffree       Releases memory back to the far heap (reverse _fmalloc)

         _fheapchk    Verifies the integrity of the far heap

       * _fheapdump   Creates a detailed report on the state of the far heap

       * _fheappack   Returns far heap memory to the operating system.

         _fheapset    Fills unused far heap memory with a single value

         _fheapwalk   Traverse the far heap, reporting on each entry

       * _fheapwatch  Establishes read-only heap entries to be monitored

         _fmalloc     Allocates memory from the far heap

         _fmsize      Reports size of a far heap entry

         free         Releases memory back to the default heap (reverse malloc)

         _freect      Estimates number of items that could be allocated (near)

       * _frelocate   Repositions a block as low as possible in the far heap 

         halloc       Allocates storage for a huge array from the far heap

         _heapchk     Verifies the integrity of the default heap

         _heapset     Fills unused default heap memory with a single value

       * _heapstat    Translates heap status codes to text strings

         _heapwalk    Traverses the default heap, reporting on each entry

       * _hexpand     Changes the size of a huge block in the far heap

         hfree        Releases memory back to the far heap (reverse halloc)

       * _hmsize      Reports size of a huge block in the far heap

       * hrealloc     Reallocates a huge block in the far heap

         malloc       Allocates memory from the default heap

         _memavl      Estimates amount of memory available in near heap

         _memmax      Estimates size of largest free area in near heap

         _msize       Reports size of a default heap entry

         _nfree       Releases memory back to the near heap (reverse _nmalloc)

         _nheapchk    Verifies the integrity of the near heap

         _nheapset    Fills unused near heap memory with a single value

         _nheapwalk   Traverses the near heap, reporting on each entry

         _nmalloc     Allocates memory from the near heap

         _nmsize      Reports size of a near heap entry

         realloc      Reallocates a block in the default heap

         sbrk         Resets break value

         stackavail   Reports stack space available for alloca


      b. Brief descriptions

         These functions are unique to the replacement heap manager
         library.  The standard functions are described on page 69 of
         the MSC 5.1 Optimizing Compiler Run-Time Library manual.

         _Fheapdump() is a utility function that writes a complete
         description of the state of the heap to the indicated
         stream file.  Verbose is a boolean argument that controls
         the level of detail in the heap status report.  In non-verbose
         mode the report excludes the chunk info.

         _Fheappack() releases unused heap memory back to DOS.  It
         searches the entire heap, shrinking arenas that contain
         active entries to the minimum, and totally freeing arenas
         that contain no active entries.

         _Fheapwatch() establishes a heap entry as read-only.  It
         records a checksum which is tested by the _heapchk/set/walk()
         functions, and monitored by the _HEAPDEBUG and _HEAPTRACE
         routines.

         _Frelocate() repositions a heap entry as low as possible
         in memory.  It is the basis for garbage collection to
         relieve heap fragmentation, and, with _fheappack(),
         supports heap compaction.

         _Heapstat() translates heap status codes obtained from
         _heapchk(), _heapset(), and _heapwalk() into descriptive
         strings.

         _Hexpand is a "huge" version of _expand().  It is identical
         except that it takes a long argument for size.

         _Hmsize() is a "huge" version of _msize().  It is identical
         except that it returns a long value for the size.

         Hrealloc() is a "huge" version of realloc().  It is identical
         except that it takes a long argument for size.


      5. Include files

         a. Heap.h

            The include file heap.h is a replacement for the MSC include
            file malloc.h.  It provides transparent access to all of
            the functionality of the original heap manager, plus the
            extended capabilities of the replacement heap manager.  The
            symbol STDMSC enforces strict compatibility by disabling all
            the extended features of the replacement heap manager.

            Heap.h declares the following functions:

                alloca                    _heapstat
                calloc     *              _heapwalk      @
                expand     *              _hexpand   *
                _ffree     *              hfree      *
                _fheapchk                 _hmsize    *
                _fheapdump                hrealloc   *
                _fheappack *              malloc     *
                _fheapset                 _memavl
                _fheapwalk                _msize     *
                _fheapwatch               _nfree
                _fmalloc   *              _nheapchk
                _fmsize    *              _nheapset
                free       *              _nheapwalk
                _freect                   _nmalloc
                _frelocate *              _nmsize
                halloc     *              realloc    * +
                _heapchk       @          sbrk
                _heapset       @          stackavail

                * these functions have alternates for debugging.

                + these functions include bug fixes

                @ these functions are implemented as macros


            SIZE_MAX is also declared in heap.h.


         b. Heap.i

            The include file heap.i is an internal header file for
            the heap manager routines only.  It is not necessary
            for any application program to include it.

            The heap.i file declares a variety of pre-processor macros
            for use by the heap functions.  It also defines the internally
            shared variables and functions.


II. Reference

    The replacement heap managment functions are listed here, one per page,
    in alphabetical order.  These descriptions rely on the information
    contained in the MSC 5.1 Optimizing Compiler Run-Time Library Reference.

    The example programs were tested under all address models.


ALLOCA

    Summary

        #include <heap.h

        void *alloca( size );
        size_t size;                    // Bytes to allocate


    Differences

        None.


    Further info

        See page 114 of the MSC 5.1 Optimizing Compiler Run-Time Reference


CALLOC

    Summary

        #include <heap.h>

        void *calloc( nitems, size )
        size_t nitems;                  // Number of array elements
        size_t size;                    // Bytes in each element

        #if !defined( STDMSC ) && !defined( NDEBUG ) && defined( _DATA_FAR )

        void far *calloc_d( nitems, size, file, line, stream );  // debug
        void far *calloc_t( nitems, size, file, line, stream );  // trace
        size_t     nitems;              // Number of array elements
        size_t     size;                // Bytes in each element
        char near *file;                // Name of source file (__FILE__)
        uint       line;                // Source file line number (__LINE__)
        FILE      *stream;              // Error output file

        #endif



    Differences

        In "small" and "medium" model programs calloc comes from the
        original library.  In "compact", "large", and "huge" model
        programs calloc comes from the replacement library, and differs
        from the original in the following ways:

            1. SIZE_MAX is 65535 rather than 65516.

            2. The _HEAPDEBUG symbol enables the debugging alternate
               version of calloc.  Prior to every heap access it checks
               the heap status via _fheapchk, and reports errors
               on the indicated stream file with _heapdump.
               
            3. The _HEAPTRACE symbol enables the tracing alternate
               version of calloc.  In addition to the debugging described
               under _HEAPDEBUG, after every heap transaction it reports the
               nature of the transaction, its source-code location, and the
               values of the arguments and returned result. 
 

    Further info

        See page 150 of the MSC 5.1 Optimizing Compiler Run-Time Reference


_EXPAND

    Summary

        #include <heap.h>

        void *_expand( buffer, size )
        void  *buffer;                  // Pointer to memory block
        size_t size;                    // Desired number of bytes

        #if !defined( STDMSC ) && !defined( NDEBUG ) && defined( _DATA_FAR )

        void far *_expand_c( buffer, size, file, line, stream );  // check ptr
        void far *_expand_d( buffer, size, file, line, stream );  // debug
        void far *_expand_t( buffer, size, file, line, stream );  // trace
        void far  *buffer;              // Pointer to memory block
        size_t     size;                // Desired number of bytes
        char near *file;                // Name of source file (__FILE__)
        uint       line;                // Source file line number (__LINE__)
        FILE      *stream;              // Error output file

        #endif


    Differences

        In "small" and "medium" model programs _expand comes from the
        original library.  In "compact", "large", and "huge" model
        programs _expand comes from the replacement library, and differs
        from the original in the following ways:

            1. SIZE_MAX is 65535 rather than 65516.

            2. Since the "huge" heap is part of the "far" heap,
               _expand can handle any "huge" heap entry.

            3. Invalid pointers are ignored by _expand, which
               returns NULL when one is detected.

            4. The _HEAPCHECK symbol enables the pointer checking
               alternate version of _expand, which reports invalid
               pointers, detailing the location of the offending
               function in the source code.

            5. The _HEAPDEBUG symbol enables the debugging alternate
               version of _expand.  In addition to the pointer checking
               described under _HEAPCHECK, prior to every heap access it
               checks the heap status via _fheapchk, and reports errors
               on the indicated stream file with _heapdump.
               
            6. The _HEAPTRACE symbol enables the tracing alternate
               version of _expand.  In addition to the debugging described
               under _HEAPDEBUG, after every heap transaction it reports the
               nature of the transaction, its source-code location, and the
               values of the arguments and the returned result. 
 

    Further info

        See page 246 of the MSC 5.1 Optimizing Compiler Run-Time Reference



_FFREE

    Summary

        #include <heap.h>

        void _ffree( buffer )
        void far *buffer;               // Pointer to memory block

        #if !defined( STDMSC ) && !defined( NDEBUG )

        void _ffree_c( buffer, file, line, stream );  // check pointers
        void _ffree_d( buffer, file, line, stream );  // debug
        void _ffree_t( buffer, file, line, stream );  // trace
        void far  *buffer;              // Pointer to memory block
        size_t     size;                // Desired number of bytes
        char near *file;                // Name of source file (__FILE__)
        uint       line;                // Source file line number (__LINE__)
        FILE      *stream;              // Error output file

        #endif


    Differences

        The replacement version of _fmalloc differs from the original
        in the following ways:

            1. Since the "huge" heap is part of the "far" heap,
               _ffree can handle any "huge" heap entry.

            2. Invalid pointers are ignored by _ffree.

            3. The _HEAPCHECK symbol enables the pointer checking
               alternate version of _ffree, which reports invalid
               pointers, detailing the location of the offending
               function in the source code.

            4. The _HEAPDEBUG symbol enables the debugging alternate
               version of _ffree.  In addition to the pointer checking
               described under _HEAPCHECK, prior to every heap access it
               checks the heap status via _fheapchk, and reports errors
               on the indicated stream file with _heapdump.
               
            5. The _HEAPTRACE symbol enables the tracing alternate
               version of _ffree.  In addition to the debugging described
               under _HEAPDEBUG, after every heap transaction it reports the
               nature of the transaction, its source-code location, and the
               values of the arguments and the returned result.