heap.man

一个堆栈管理器的源码

 

    Further info

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

_FHEAPCHK

    Summary

        #include <heap.h>

        int _fheapchk( void );


    Differences

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

            1. It performs a detailed consistency check on each heap
               entry, verifying the validity of the heap control block
               and checking its neighbors for reciprocity.

            2. The safety margins controlled by _heappad are inspected
               for changes.  Any alteration of the safety margins
               produces a _HEAPBADPTR result code.

            3. The checksums on the read-only heap entries established
               by _fheapwatch are recalculated.  A changed checksum
               produces a _HEAPBADPTR result code


    Further info

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

_FHEAPDUMP

    Summary

        #include <heap.h>

        #if !defined( STDMSC )

        void _fheapdump( stream, verbose );
        FILE *stream;                       // Where to write the report
        int verbose;                        // Whether to give details

        #endif


    Description

        The _fheapdump function provides a detailed report on the state
        of the far heap.  The report includes the following information:

             - Key to notation

             - Global variables
                - _heapmode
                - _heappad

             - Arena headers -- DOS interface
                - Address [pointer]
                - Size
                - Links [pointers] on arena list
                - Source of the memory (DOS or non-DOS)
                - Chunk headers -- C interface
                   - Address {<pointer>}
                   - Size
                   - Links <pointers> on chunk list
                   - Links {pointers} on free list
                   - Status: readonly, damaged, OK, etc.
                   - In debug mode additional info is reported:
                      - Function that last changed the entry
                      - Desired size of the entry
                      - Transaction (sequence) number
                      - Name of source file (__FILE__)
                      - Line number in source file (__LINE__)

             - Controls for free and join lists
                - Address {pointer}
                - Number of entries on the list (not including master)
                - Links {pointers}

             - Summary statistics on heap usage
                - Size of largest free block
                - Number of entries in the heap
                - Total heap memory
                - Percent of heap memory in use

             - Pagination: formfeed

        The report is written to the indicated stream file.  If verbose
        is false (zero) the details on individual chucks are excluded
        from the report.  If verbose is -1 debug information is included
        in the report.


    Return Value

        None.


    Differences

        The _fheapdump function is unique to the replacement heap manager.


    See Also

        _fheapchk, _fheapset, _fheapwalk, _fheapwatch

        All functions with '_d' and '_t' suffixes use _fheapdump to
        report errors.


    Example

        #include <stdio.h>

        #include <heap.h>

        int main()
        {
        _fmalloc( 1000 );

        _fmalloc( 2000 );

        _fheapdump( stdout, 1 );

        return( 0 );
        }

        This program allocates two heap entries and then produces
        a report on the state of the heap.


_FHEAPPACK

    Summary

        #include <heap.h>

        #if #defined( STDMSC

        int _fheappack( void );

        #endif

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

        int _fheappack_d( void );   // debug
        int _fheappack_t( void );   // trace

        #endif


    Description

        The _fheappack() function shrinks the "far" heap to the minimum
        required to contain the in-use heap entries.  Arenas containing
        no entries are returned to the operating system.  Mixed arenas
        are reduced as much as possible.

        The alternate forms of _fheappack are controlled as follows:

            1. The _HEAPDEBUG symbol enables the debugging alternate
               version of _fheappack.  Prior to every heap access it checks
               the heap status via _fheapchk, and reports errors
               on the indicated stream file with _heapdump.
               
            2. The _HEAPTRACE symbol enables the tracing alternate
               version of _fheappack.  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. 


    Return Value

        Zero if successful, otherwise a DOS error number.


    Differences

        The _fheappack function is unique to the replacement heap manager.


    See Also

        _frelocate


    Example

        #include <stdio.h>

        #include <heap.h>

        int main()
        {
        void far *p1 = _fmalloc( 1000 );

        void far *p2 = _fmalloc( 2000 );

        void far *p3 = _fmalloc( 3000 );

        _ffree( p2 );

        _ffree( p3 );

        printf("Before packing\n\n");

        _fheapdump( stdout, 1 );

        _fheappack();

        printf("After packing\n\n");

        _fheapdump( stdout, 1 );

        return( 0 );
        }

        This program allocates three heap entries and then frees the
        last two.  Then it packs the heap to minimize the amount of
        space taken up by the "far" heap.  The before and after heap
        reports illustrate the savings.


_FHEAPSET


    Summary

        #include <heap.h>

        int _fheapset( fill );
        uint fill;                      // Value to fill with


    Differences

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

            1. It performs a detailed consistency check on each heap
               entry, verifying the validity of the heap control block
               and checking its neighbors for reciprocity.

            2. The safety margins controlled by _heappad are inspected
               for changes.  Any alteration of the safety margins
               produces a _HEAPBADPTR result code.

            3. The checksums on the read-only heap entries established
               by _fheapwatch are recalculated.  A changed checksum
               produces a _HEAPBADPTR result code

            4. The default safety margin fill value is reset by each call
               to _fheapset.


    Further info

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

_FHEAPWALK

    Summary

        #include <heap.h>

        int _fheapwalk( info );
        struct _heapinfo *info;         // Info on one heap entry


    Differences

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

            1. It performs a detailed consistency check on each heap
               entry, verifying the validity of the heap control block
               and checking its neighbors for reciprocity.

            2. The safety margins controlled by _heappad are inspected
               for changes.  Any alteration of the safety margins
               produces a _HEAPBADPTR result code.

            3. The checksums on the read-only heap entries established
               by _fheapwatch are recalculated.  A changed checksum
               produces a _HEAPBADPTR result code

        
    Further info

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

_FHEAPWATCH

    Summary

        #include <heap.h>

        #if !defined( STDMSC )

        int _fheapwatch( buffer, enable )
        void far *buffer;              // Pointer to memory block
        int       enable;              // Turns monitoring on and off

        #endif


    Description

        The _fheapwatch function establishes a heap entry as read-only.
        The region is checksummed, and the _heapchk/set/walk family of
        functions verify the integrity of the entry by recalculating
        the checksum each time they are used.  The heap debug monitor
        also checks the read-only entries and triggers a diagnostic
        report if one is changed.

        If the enable argument is TRUE the checksum is calculated and
        the region is treated as read-only.  If the enable argument is
        FALSE the region loses its read-only status.

        A program may alter a read-only heap entry and inform the heap
        manager that the change is not an error by calling _fheapwatch
        after each alteration.

        Note that _expand, _frelocate, _hexpand, hrealloc, realloc, and
        all forms of free automatically remove the read-only status of
        a heap entry.

        If the buffer argument is an invalid pointer _fheapwatch
        ignores the entry.
        

    Return Value

        A successful invocation returns zero.  If the pointer does not
        address a valid heap entry _fheapwatch returns non-zero.


    Differences

        The _fheapwatch function is unique to the replacement heap manager.


    See Also

        _fheapchk, _fheapdump, _fheapset, _fheapwalk


    Example

        #include <stdio.h>

        #include <heap.h>

        void report( char *position );

        int main()
        {
        int index;