New in SmartHeap 5.0

New small-block allocator

An improved small-block allocator incurs zero bytes per allocation of overhead and recycles space more effectively between block sizes than the SmartHeap 3.x/4.x small-block allocator.Ê If you want to use the old small-block allocator for some reason, you may use MemPoolSetSmallBlockAllocator to change the small-block allocator for a given memory pool.Ê Use MemPoolSetSmallBlockAllocator(MemDefaultPool, MEM_SMALL_BLOCK_SH3) to use the SH 3.0/4.0 small-block allocator.Ê Specify the value MEM_SMALL_BLOCK_SH5 for the new small-block allocator.

Reduced space overhead

In addition to the more space-efficient small-block allocator, SmartHeap 5.0 no longer creates multiple default memory pools for multi-threaded applications, so multiple threads are able to share the same pages of heap memory in a contention-free manner rather than using separate memory pools.

New API to control process heap growth

SmartHeap 5.0 has a new API, MemProcessSetGrowIncrement, that allows you to control how much memory SmartHeap requests from the operating system when a memory pool needs to grow. The memory returned is retained in SmartHeapâs free pool and is allocated to any memory pool(s) that subsequently need to grow.Ê By buffering operating system heap requests, SmartHeap 5.0 incurs less system call overhead, less operating system heap and address space fragmentation, and less operating system heap contention.

The default process grow increment is 2MB.Ê The value you specify to MemProcessSetGrowIncrement is in bytes and is rounded up to the next 64K.

Installing SmartHeap

The files on the SmartHeap installation disks are not compressed or copy protected.Ê

¯ To install SmartHeap on your hard disk:

1.ÊÊ Copy the files in the include directory to a directory on your compilerâs include file path.

2.ÊÊ Copy the files in the library directory corresponding to your compiler (msvc) to a directory on your linkerâs library file path.

3.ÊÊ Copy the files in the bin directory to the Windows NT system32 or Windows 95 system directory, or some other directory on the PATH.

4.ÊÊ (optional)Ê Copy the files from source and/or samples to examine or modify the SmartHeap source files and sample applications.

Files in the Win32 SmartHeap release

The Win32 version of SmartHeap includes:

áÊÊÊÊÊ Import libraries for Microsoft Visual C++.

áÊÊÊÊÊ Statically linkable libraries for Microsoft Visual C++.

áÊÊÊÊÊ Compiler-independent DLLs.

áÊÊÊÊÊ Platform-independent header files.

áÊÊÊÊÊ Platform-independent source files for the malloc and C++ operator new definitions.

The SmartHeap diskette contains the following Win32öspecific files:

DirectoryÊÊÊÊÊÊÊÊÊ FileÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ Description

includeÊÊÊÊ smrtheap.hÊÊÊ Header file containing all Runtime SmartHeap C declarations except malloc.

includeÊÊÊÊ smrtheap.hppÊ Header file containing Runtime SmartHeap C++ declarations, including operator new.

includeÊÊÊÊ shmalloc.hÊÊÊ Header file containing declarations for Runtime SmartHeap ANSI C functions (malloc, etc.).

includeÊÊÊÊ heapagnt.hÊÊÊ Header file containing all Debug SmartHeap declarations.

binÊÊÊÊÊÊÊÊ shw32.dllÊÊÊÊ Runtime SmartHeap dynamic link library.

binÊÊÊÊÊÊÊÊ shw32.dbgÊÊÊÊ Symbols for Runtime SmartHeap DLL.

binÊÊÊÊÊÊÊÊ ha312w32.dllÊ Debug SmartHeap dynamic link library.

msvcÊÊÊÊÊÊÊ smrtheap.cÊÊÊ Source file for ãquick startä procedure when using SmartHeap with a non-MFC application..

msvcÊÊÊÊÊÊÊ shmfc.cppÊÊÊÊ Source file for ãquick startä procedure when using SmartHeap with an MFC application..

msvcÊÊÊÊÊÊÊ shlw32m.libÊÊ Runtime SmartHeap single-thread statically linkable library for Microsoft Visual C++.

msvcÊÊÊÊÊÊÊ shdw32m.libÊÊ Runtime SmartHeap single-thread DLL import library for Microsoft Visual C++.

msvcÊÊÊÊÊÊÊ shlw32mt.libÊÊÊ Runtime SmartHeap multi-thread statically linkable library for Microsoft Visual C++.

msvcÊÊÊÊÊÊÊ shdw32mt.libÊÊÊ Runtime SmartHeap multi-thread DLL import library for Microsoft Visual C++.

msvcÊÊÊÊÊÊÊ shmfc4m.libÊÊ Statically linkable single-thread library file for Microsoft Visual C++/MFC 4.x/5.x ÷ for statically linked Release MFC only; must link before SmartHeap library.

msvcÊÊÊÊÊÊÊ shmfc4mt.libÊ Statically linkable multi-thread library file for Microsoft Visual C++/MFC 4.x/5.x ÷ for statically linked Release MFC only; must link before SmartHeap library.

DirectoryÊÊÊÊÊÊÊÊÊ FileÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ Description

msvcÊÊÊÊÊÊÊ haw32m.libÊÊÊÊÊÊÊÊ Debug SmartHeap multi-thread DLL import library for Microsoft Visual C++.

msvcÊÊÊÊÊÊÊ hamfc32m.libÊ Statically linkable library file for Microsoft Visual C++ 2.x/MFC 3.0 ÷ for statically linked _DEBUG MFC only; must link before Debug SmartHeap library.

msvcÊÊÊÊÊÊÊ hamfc4m.libÊÊ Statically linkable library file for Microsoft Visual C++/MFC 4.x/5.x ÷ for statically linked _DEBUG MFC only; must link before Debug SmartHeap library.

borlandÊÊÊÊ shdw32b.libÊÊ Runtime SmartHeap single-thread DLL import library for Borland C++ (Intel only).

borlandÊÊÊÊ shdw32bt.libÊ Runtime SmartHeap multi-thread DLL import library for Borland C++ (Intel only).

borlandÊÊÊÊ haw32b.libÊÊÊ Debug SmartHeap multi-thread DLL import library for Borland C++ (Intel only).

sourceÊÊÊÊÊ shmalloc.cÊÊÊ SmartHeap definition for ANSI C (malloc, etc.) functions ÷ provided so you can customize these.

sourceÊÊÊÊÊ shmalmac.cÊÊÊ Macro versions of SmartHeap ANSI C (malloc, etc.) functions.

sourceÊÊÊÊÊ shnew.cppÊÊÊÊ SmartHeap definition for operator new ÷ provided so you can customize and/or build a library for non-supported compilers.

sourceÊÊÊÊÊ shnewhnd.cppÊ SmartHeap new handler definitions

sourceÊÊÊÊÊ def*.c,ÊÊÊÊÊÊ Default memory pool definitions

ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ db*.cÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ used by the above malloc and new definitions.

samplesÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ Various sample SmartHeap applications with Microsoft Visual C++ and Borland C++ make files.

Using SmartHeap with Microsoft Visual C++

If youâre developing an application with Microsoft Visual C++ for 32-bit Windows, hereâs how to get started with SmartHeap.Ê

Quick start

If your goal is to quickly get SmartHeap into your project so that it simply replaces malloc and operator new in your application, follow the instructions in this section.Ê This procedure uses a source file with #pragma statements that force references to the correct set of SmartHeap libraries for your application based on your projectâs compile-time flags.Ê This method is better than explicitly referencing SmartHeap libraries, because it ensures that the correct SmartHeap libraries are linked ö both initially and whenever you subsequently change your project settings.

If you want to use SmartHeap APIs, or if you want explicit control of which SmartHeap libraries your application uses, see the detailed instructions in the sections ãSetting up your application for the SmartHeap runtime libraryä and ãDebugging an application with SmartHeap,ä later in this booklet.

Specifying the location of SmartHeap files

¯ To tell Visual C++ where to find SmartHeap include and library files:

1.ÊÊ From the Visual C++ Tools menu, choose Options, and the Options dialog box appears.

2.ÊÊ Choose the Directories tab.Ê

3.ÊÊ Under Show Directories For, choose ãInclude filesä.

4.ÊÊ Choose the Add button, and add the path of the SmartHeap include directory to the include path list, for example:Ê

ÊÊÊÊ c:\smrtheap\include

5.ÊÊ Choose the Add button again, and add the path of the SmartHeap msvc directory to the include path list, for example:Ê

ÊÊÊÊ c:\smrtheap\msvc

6.ÊÊ Under Show Directories For, choose ãLibrary filesä.

7.ÊÊ Choose the Add button, and add the path of the SmartHeap msvc directory to the library path list, for example:Ê

ÊÊÊÊ c:\smrtheap\msvc

8.ÊÊ Choose OK to save your changes.

Setting up a Visual C++ MFC project

¯ To set up a Visual C++ MFC project to work with SmartHeap:

1.ÊÊ Open the file stdafx.cpp in your project.

2.ÊÊ At the beginning of stdafx.cpp, before any #include statements, insert the following text:

ÊÊÊÊ #include "shmfc.cpp"

3.ÊÊ Save your changes to stdafx.cpp.

4.ÊÊ Choose Rebuild All from the Project menu (Visual C++ 2.x) or from the Build menu (Visual C++ 4.x/5.x).

5.ÊÊ Repeat the Rebuild All command for both the Release and Debug project configurations.

Setting up a Visual C++ non-MFC project

¯ To set up a Visual C++ project to work with SmartHeap if the project does not use MFC:

1.ÊÊÊ Open your applicationâs project file.

2.ÊÊÊ Add the file smartheap.c to your project.Ê This file is located in the SmartHeap msvc directory.Ê

3.ÊÊÊ Display the Project Settings dialog box.

4.ÊÊÊ Under Settings For, choose ãWin32 Releaseä, if it isnât chosen already.

5.ÊÊÊ Choose the Link tab.

6.ÊÊÊ At the beginning of ãObject/library modulesä, before any other object files or libraries, enter the following:

ÊÊÊÊ .\Release\smrtheap.obj

7.ÊÊ Under Settings For, choose ãWin32 Debugä.

8.ÊÊ Choose the Link tab.

9.ÊÊ At the beginning of ãObject/library modulesä, before any other object files or libraries, enter the following:

ÊÊÊÊ .\Debug\smrtheap.obj

10.Ê Choose OK to save changes to Project Settings.Ê

11.Ê Rebuild both Release and Debug versions of the project.

Setting up your application for the SmartHeap runtime library

Hereâs the detailed procedure for setting up your application to use the SmartHeap runtime library.Ê For information on debugging your application with Debug SmartHeap, see ãDebugging an application with SmartHeap,ä later in this booklet.

Adding the SmartHeap header file to your source files

Important!Ê If youâre not calling SmartHeap APIs, skip to the next page.Ê You donât need to add SmartHeap header files if you simply want SmartHeap to replace malloc and operator new.Ê

¯ For each file that makes SmartHeap API calls:

¬ÊÊÊ For C source files, include smrtheap.h, which contains declarations for the C SmartHeap APIs.

ÊÊÊÊÊÊ #include <smrtheap.h>

¬ÊÊÊ For C++ source files, include smrtheap.hpp, which contains declarations for SmartHeap versions of operator new and which itself includes smrtheap.h.

ÊÊÊÊÊÊ #include <smrtheap.hpp>

In both cases, the #include directive must appear after any compiler or library header files that declare malloc (for example, stdlib.h) or new (for example, new.h or afx.h).

Specifying the location of SmartHeap files

¯ To tell Visual C++ where to find SmartHeap include and library files:

1.ÊÊ Choose Options from the Visual C++ Tools menu, and the Options dialog box appears.

2.ÊÊ Choose the Directories tab.Ê

3.ÊÊ Under Show Directories For, choose ãInclude files.ä

4.ÊÊ Choose the Add button, and add the path of the SmartHeap include directory to the include path list, for example:Ê

ÊÊÊÊÊ c:\smrtheap\include

5.ÊÊ Again under Show Directories For, choose ãLibrary files.ä

6.ÊÊ Choose the Add button, and add the path of the SmartHeap msvc directory to the library path list, for example:Ê

ÊÊÊÊÊ c:\smrtheap\msvc

7.ÊÊ Choose OK to save your changes.

Setting up the Visual C++ project file

Hereâs how you set up a Visual C++ project file to work with SmartHeap.Ê

NoteÊ You must repeat the following procedure for each EXE and DLL in your application.Ê

¯ To set up a Visual C++ project to work with SmartHeap:

1.ÊÊ Choose Open Workspace from the Visual C++ File menu, and open your applicationâs project file.

2.ÊÊ Choose Settings from the Project menu (Visual C++ 2.x) or Build menu (Visual C++ 4.x/5.x), and the Project Settings dialog box appears.

3.ÊÊ Under Settings For, choose ãWin32 Release,ä if it isnât chosen already.

4.ÊÊ Choose the Link tab.

5.ÊÊ Specify the SmartHeap libraries that you want to link with.Ê At the beginning of Object/Library Modules, before any Visual C++ libraries, enter the appropriate libraries:

ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ Link with these libraries
If youâre using the SmartHeap DLL withÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ (in the order shown)

An EXE or DLL in a single-threaded app,
without MFC, with statically linked MFC 3.0,
or the MFC 3.0/4.x DLLÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ shdw32m.lib

An EXE or DLL in a multi-threaded app,
without MFC, with statically linked MFC 3.0,
or the MFC 3.0/4.x DLLÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ shdw32mt.lib

An EXE or DLL with a single-threaded app,
with statically-linked MFC 4.xÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ shmfc4m.lib, shdw32m.lib

An EXE or DLL with a multi-threaded app,
with statically-linked MFC 4.xÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ shmfc4mt.lib, shdw32mt.lib

ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ Link with these libraries
If youâre statically linking SmartHeap withÊÊÊÊÊÊÊÊÊÊÊ (in the order shown)

An EXE or DLL in a singled-threaded app,
without MFC, or with statically-linked MFC 3.0ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ shlw32m.lib

An EXE or DLL in a multi-threaded app,
without MFC, or with statically-linked MFC 3.0ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ shlw32mt.lib

An EXE or DLL in a single-threaded app,
with statically-linked MFC 4.xÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ shmfc4m.lib, shlw32m.lib

An EXE or DLL in a multi-threaded app,
with statically-linked MFC 4.xÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ shmfc4mt.lib, shlw32mt.lib

NoteÊ The above library files appear in the msvc sub-directory under the directory where you installed SmartHeap.Ê

MFC users!Ê If your application uses the DLL version of MFC, you must use the DLL version of SmartHeap (shdw32m.lib).Ê If your application links with Debug MFC, you must link with Debug SmartHeap.

Caution!Ê If your application has more than one thread, you must link with the multi-thread SmartHeap 4.0 libraries.Ê In previous versions of SmartHeap, all libraries were thread-reentrant as long as the MEM_POOL_SERIALIZE flag was specified.Ê In SmartHeap 4.0, only libraries whose names end it Îtâ are thread-reentrant.

6.ÊÊ Choose OK to save changes to Project Settings.Ê

7.ÊÊ Choose Build filename from the Project menu (Visual C++ 2.x) or Build menu (Visual C++ 4.x/5.x), and Visual C++ relinks the application.

Debugging an application with SmartHeap

Hereâs the detailed procedure for setting up your application for debugging with Debug SmartHeap.Ê

Adding the Debug SmartHeap header file to your source files

If you want to call Debug SmartHeap APIs (dbgMemXXX), youâll need to include the Debug SmartHeap header file and recompile your application.Ê

NoteÊ Simply linking with the Debug SmartHeap Library is sufficient to allow SmartHeap to perform full error detection.Ê Moreover, if your application is compiled with Visual C++ PDB debugging information, Debug SmartHeap obtains file names and line numbers directly from the debugging information.Ê So if you arenât calling Debug SmartHeap APIs, there is no need to recompile your application for Debug SmartHeap.

Alpha users!Ê For non-Intel platforms, Debug SmartHeap is not able to obtain file and line information from Visual C++ PDB debug information.Ê Therefore, if youâre using the Alpha version of SmartHeap and if you want Debug SmartHeap to include file names and line numbers in error reports, you must include heapagnt.h in your source files and define the preprocessor constants MEM_DEBUG and DEFINE_NEW_MACRO.

¯ For each file from which you call Debug SmartHeap APIs:

¬ÊÊÊ Include heapagnt.h, which contains declarations of memory-allocation functions both for ANSI C (malloc, free, and so on) and for C++ (including the new and delete operators).Ê The #include directive must appear after any compiler or library header files that declare malloc (for example, stdlib.h) or new (for example, new.h or afx.h):

ÊÊÊÊÊÊ #include <heapagnt.h>

NoteÊ If you already include smrtheap.h, shmalloc.h, or smrtheap.hpp, then you donât need to also include heapagnt.h.Ê The Runtime SmartHeap header files automatically include heapagnt.h when MEM_DEBUG is defined.

Specifying the location of Debug SmartHeap files

¯ To tell Visual C++ where to find Debug SmartHeap include and library files:

1.ÊÊ Choose Options from the Visual C++ Tools menu, and the Options dialog box appears.

2.ÊÊ Choose the Directories tab.Ê

3.ÊÊ Under Show Directories For, choose ãInclude files.ä

4.ÊÊ Choose the Add button, and add the path of the Debug SmartHeap include directory to the include path list, for example:Ê

ÊÊÊÊ c:\smrtheap\include

5.ÊÊ Again under Show Directories For, choose ãLibrary files.ä

6.ÊÊ Choose the Add button, and add the path of the Debug SmartHeap msvc directory to the library path list, for example:Ê

ÊÊÊÊ c:\smrtheap\msvc

7.ÊÊ Choose OK to save your changes.

Setting up the Visual C++ project file

Hereâs how you set up a Visual C++ project file so you can debug the corresponding EXE or DLL with Debug SmartHeap.Ê

NoteÊ You must repeat the following procedure for each EXE and DLL in your application.Ê

¯ To set up a Visual C++ project to work with Debug SmartHeap:

1.ÊÊ Choose Open Workspace from the Visual C++ File menu, and open your applicationâs project file.

2.ÊÊ Choose Settings from the Project menu (Visual C++ 2.x) or Build menu (Visual C++ 4.x/5.x), and the Project Settings dialog box appears.

3.ÊÊ Under Settings For, choose ãWin32 Debug,ä if it isnât chosen already.

4.ÊÊ Choose the C/C++ tab and, under Debug Info, choose ãProgram Database.ä

5.ÊÊ (required for Alpha and PowerPC, optional otherwise)Ê If youâre using Intel SmartHeap, and if your application doesnât call Debug SmartHeap APIs, you can skip this step.

Still at the C/C++ tab, in Preprocessor Definitions, add:

ÊÊÊÊ MEM_DEBUG=1

6.ÊÊ (Alpha and PowerPC only)Ê Also in Preprocessor Definitions, add:

ÊÊÊÊ DEFINE_NEW_MACRO=1

7.ÊÊ Choose the Link tab.

8.ÊÊ Check the Generate Debug Info checkbox.

9.ÊÊ Still at the link tab, based on the following table, specify the Debug SmartHeap libraries that you want to link with.Ê At the beginning of Object/Library Modules, before the Visual C++ libraries, enter the appropriate libraries:

ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ Link with these libraries
If youâre debuggingÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ (in the order shown)

An EXE or DLL without MFC, with non-Debug MFC,
or with the Debug MFC DLLÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ haw32m.lib

An EXE or DLL with Debug MFC 3.0 statically linkedÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ hamfc32m.lib,
ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ haw32m.lib

An EXE or DLL with Debug MFC 4.x statically linkedÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ hamfc4m.lib,
ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ haw32m.lib

NoteÊ The files haw32m.lib, hamfc32m.lib, and hamfc4m.lib appear in the msvc sub-directory under the directory where you installed SmartHeap.Ê

10.Ê Choose OK to save changes to Project Settings.Ê

Recompiling or relinking your application

If youâre calling Debug SmartHeap APIs, or if youâre using the Alpha version of SmartHeap, you need to include the Debug SmartHeap header file and recompile your application.Ê Information on including this header file appears at the beginning of the section.

NoteÊ You only need to recompile your application if youâve included the Debug SmartHeap header file in one or more of your source files.Ê However, you must always relink each EXE and DLL in your application for Debug SmartHeap.

¯ To recompile your application:

1.ÊÊ From the File menu, choose Open Workspace, and open your applicationâs project file, if you havenât already done so.

2.ÊÊ Choose Rebuild All from the Project menu (Visual C++ 2.x) or from the Build menu (Visual C++ 4.x/5.x), and Visual C++ compiles the application.

¯ To relink your application:

1.ÊÊ From the File menu, choose Open Workspace, and open your applicationâs project file, if you havenât already done so.

2.ÊÊ Choose Build filename from the Project menu (Visual C++ 2.x) or from the Build menu (Visual C++ 4.x/5.x), and Visual C++ relinks the application.

SmartHeap/Microsoft Visual C++ compatibility issues

Resolving Visual C++ duplicate-definition linker errors

If your application does not reference the functions malloc and free, you may receive duplicate-definition linker errors when you try to link the SmartHeap library into your application.Ê To eliminate these linker errors, use the following procedure:

1.ÊÊÊ From the File menu, choose Open Workspace, and open your applicationâs project file, if you havenât already done so.

2.ÊÊÊ Choose Settings from the Project menu (Visual C++ 2.x) or from the Build menu (Visual C++ 4.x/5.x), and the Project Settings dialog box appears.

3.ÊÊÊ Choose the Link tab, and select the Input category.

4.ÊÊÊ In Force Symbol References, add the symbol _SmartHeap_malloc.

Alternatively, if youâre using the command-line linker, add the following linker option:

-include:_SmartHeap_malloc

Using SmartHeap with Visual C++ 4.x Debug C runtime libraries

Visual C++ 4.0 and higher includes debugging versions of the C runtime libraries.Ê Debug SmartHeap supports these libraries, but Runtime SmartHeap does not.Ê Therefore, if your application links with the Debug C runtime library, it must also link with the Debug SmartHeap library (haw32m.lib) rather than the Runtime SmartHeap library (shlw32m[t].lib or shdw32m[t].lib).

Debug SmartHeap overrides the Visual C++ functions _calloc_dbg, _realloc_dbg, _free_dbg, _msize_dbg, _expand_dbg, _CrtCheckMemory, _CrtDumpMemoryLeaks, _CrtIsValidHeapPointer, _CrtIsMemoryBlock, _CrtSetAllocHook, and _CrtSetBreakAlloc.Ê Debug SmartHeap emulates the behavior of each of these Visual C++ routines, so you can use these routines interchangeably with Debug SmartHeap APIs.

Using SmartHeap with MFC 3.0/4.x

Debug SmartHeap defines replacements for all of the public memory-debugging APIs of the Microsoft Foundation Class Library.Ê This allows Debug SmartHeap to be used with _DEBUG MFC.Ê Runtime SmartHeap is not compatible with Debug MFC.Ê Debug SmartHeap emulates all MFC APIs except for AfxDoForAllObjects and the CMemoryState member functions.Ê For the unsupported APIs, SmartHeap defines stubs that print error messages that point to the corresponding SmartHeap APIs offering similar functionality.

If your application uses the statically linked Debug version of MFC, you must link with the SmartHeap/MFC integration library:Ê hamfc32m.lib for MFC 3, or hamfc4m.lib for MFC 4.x.Ê Be sure to place this library before either the SmartHeap or MFC libraries on the linker command line.Ê If your application uses the statically linked Release version of MFC 4.x, you must link with shmfc4m.lib.Ê Note that no integration is required for the Release (non-debug) version of MFC 3.0, since this library doesnât override new/delete.

The DLL version of MFC 3.0 and higher requires applications to share the same memory manager that the MFC DLL itself uses.Ê (This is a change from MFC 2.x, where the MFC DLL called back to the client application for memory management.)Ê To allow SmartHeap applications to work with the DLL version of MFC, the SmartHeap DLLs automatically patch the memory-management functions in the MFC and CRT DLLs.Ê

ImportantÊ The statically linked SmartHeap library (shlw32m.lib) does not patch MFC or CRT DLLs, so if your application uses the MFC or CRT DLLs, you must use the DLL version of SmartHeap (shdw32m.lib or haw32m.lib).

Compiler functions that SmartHeap overrides

SmartHeap overrides malloc, calloc, realloc, free, new, and delete on all platforms, as explained in ¤2.3.2, ¤2.3.3, and ¤2.3.4 of the SmartHeap Programmerâs Guide.Ê In addition, the Microsoft Visual C++ SmartHeap libraries override the following functions:

FunctionÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ SmartHeap library module

_expandÊÊÊÊÊÊÊ shmalloc

_heapchkÊÊÊÊÊÊ shmalloc

_heapminÊÊÊÊÊÊ shmalloc

_heapsetÊÊÊÊÊÊ shmalloc

_heapwalkÊÊÊÊÊ shmalloc

_msizeÊÊÊÊÊÊÊÊ shmalloc

If you donât want SmartHeap to override these C runtime functions, you should remove the applicable object module from the SmartHeap library that you link with.Ê For example, use the following command to prevent SmartHeap from overriding malloc with the statically linked Microsoft Runtime SmartHeap library:

lib shlw32m.lib /remove:shmalloc.obj

If you remove the shmalloc object module from a SmartHeap library, you will need to define SmartHeap_malloc at file scope.Ê For example:

int SmartHeap_malloc = 0;

Using SmartHeap with Borland C++

If youâre developing an application with Borland C++ version 4.x or 5.x for 32-bit Windows, hereâs how to get started with SmartHeap.Ê

Getting started with the Runtime SmartHeap library

Hereâs how you set up your application to use the Runtime SmartHeap library.Ê For information on debugging your application with Debug SmartHeap, see ãDebugging an application with SmartHeap,ä later in this booklet.

Adding the SmartHeap header file to your source files

Important!Ê If youâre not calling SmartHeap APIs, skip to the next section.Ê You donât need to add SmartHeap header files if you simply want SmartHeap to replace malloc and operator new.Ê

¯ For each file that makes SmartHeap API calls:

¬ÊÊÊ For C source files, include smrtheap.h, which contains declarations for the C SmartHeap APIs.

ÊÊÊÊÊÊ #include <smrtheap.h>

¬ÊÊÊ For C++ source files, include smrtheap.hpp, which contains declarations for SmartHeap versions of operator new and which itself includes smrtheap.h.

ÊÊÊÊÊÊ #include <smrtheap.hpp>

Setting up the Borland C++ project file

Hereâs how you set up a Borland C++ project file to work with Runtime SmartHeap.

NoteÊ You must repeat the following procedure for each EXE and DLL in your application.Ê

¯ To set up a Borland C++ project to work with Runtime SmartHeap:

1.ÊÊ Choose Open Project from the Borland C++ Project menu, and open your .ide file.

2.ÊÊ Choose Project from the Options menu, and the Project Options dialog box appears.

3.ÊÊ From the Topics list, choose Directories (if it isnât already chosen), and the directories options appear.

4.ÊÊ In the Include list, add the path of the SmartHeap include directory, for example:Ê

ÊÊÊÊÊÊÊ c:\smrtheap\include

5.ÊÊ In the Library list, add the path of the SmartHeap borland directory, for example:Ê

ÊÊÊÊÊÊÊ c:\smrtheap\borland

6.ÊÊ Choose OK to save your changes.

7.ÊÊ Add the Runtime SmartHeap Libraries that are pertinent to your application.Ê To add each library, select your projectâs EXE or DLL in the Project window, press the Insert key, and specify the file in the Add to Project List dialog box:

áÊÊÊÊÊ If youâre using SmartHeap with a single-threaded application, link with shdw32b.lib.

áÊÊÊÊÊ If youâre using SmartHeap with a multi-threaded application, link with shdw32bt.lib.

These files appear in the borland sub-directory under the directory where you installed SmartHeap.Ê

OWL users!Ê If your application uses the DLL version of OWL, you must use the DLL version of SmartHeap (shdw32b.lib or shdw32bt.lib).

8.ÊÊ Choose Make All from the Project menu, and Borland C++ links the application.

Debugging an application with SmartHeap

Hereâs how you set up your application for debugging with Debug SmartHeap.Ê

Adding the Debug SmartHeap header file to your source files

If you want Debug SmartHeap to include source file and line information in its error reports, or if you want to call Debug SmartHeap APIs (dbgMemXXX), you need to include the Debug SmartHeap header file and recompile your application.Ê

NoteÊ Simply linking with the Debug SmartHeap Library is sufficient to allow SmartHeap to perform full error detection, but in most cases youâll also want to recompile your application so that SmartHeap includes source file names and line numbers in its error reports.

¯ For each file for which you want SmartHeap to report source file and line information:

ÊÊÊÊÊÊ #include <heapagnt.h>

Setting up the Borland C++ project file

Hereâs how you set up a Borland C++ project file to work with Debug SmartHeap.

NoteÊ You must repeat the following procedure for each EXE and DLL in your application.Ê

¯ To set up a Borland C++ project to work with Debug SmartHeap:

1.ÊÊ Choose Open Project from the Borland C++ Project menu, and open your .ide file.

2.ÊÊ Choose Project from the Options menu, and the Project Options dialog box appears.

3.ÊÊ From the Topics list, choose Directories (if it isnât already chosen), and the directories options appear.

4.ÊÊ In the Include list, add the path of the SmartHeap include directory, for example:Ê

ÊÊÊÊÊÊÊ c:\smrtheap\include

5.ÊÊ In the Library list, add the path of the SmartHeap borland directory, for example:Ê

ÊÊÊÊÊÊÊ c:\smrtheap\borland

6.ÊÊ Now double-click Compiler in the Topics list, and the list expands to show the compiler options.

7.ÊÊ Choose Defines from the list, and enter this value in Defines:

ÊÊÊÊÊÊÊ MEM_DEBUG=1
DEFINE_NEW_MACRO=1

8.ÊÊ Choose OK to save your changes.

9.ÊÊ Add the Debug SmartHeap library, haw32b.lib.Ê Select your projectâs EXE or DLL in the Project window, press the Insert key, and specify the file in the Add to Project List dialog box:

This file appears in the borland sub-directory under the directory where you installed SmartHeap.Ê

Recompiling your application

If you want SmartHeap to include source file and line number information in its error reports, you need to include the Debug SmartHeap header file and recompile your application.Ê Information on including this header file appears at the beginning of the section.

¯ To recompile your application:

1.ÊÊ Choose Open Project from the Project menu, and open the .ide file, if you havenât already done so.

2.ÊÊ Choose Build All from the Project menu, and Borland C++ compiles the application.

¯ Or, to relink your application:

1.ÊÊ Choose Open Project from the Project menu, and open the .ide file, if you havenât already done so.

2.ÊÊ Choose Make All from the Project menu, and Borland C++ links the application.

SmartHeap/Borland C++ compatibility issues

Using SmartHeap with OWL

The DLL version of the Borland Object Windows Library (OWL) requires applications to share the same memory manager that the OWL DLL itself uses. To allow SmartHeap applications to work with the DLL version of OWL, the SmartHeap DLLs automatically patch the memory-management functions in the OWL and CRT DLLs.Ê

SmartHeap Win32 platform notes

Multi-threading in Win32

SmartHeap 4.0 and higher include both single- and multi-thread versions of its non-debug libraries, plus a multi-thread debug library.Ê Only the multi-thread libraries are thread reentrant.Ê If your application creates multiple threads, you must link with the multi-thread SmartHeap library ö one with a name ending in Îtâ.

NoteÊ It is not necessary to call MemRegisterTask or define MemPoolDefaultFlags in SmartHeap 4.0 and higher as it in previous SmartHeap versions and on some other platforms.Ê However, if you create your own SmartHeap memory pools, you must still specify MEM_POOL_SERIALIZE in the flags parameter if the pool is referenced in more than one thread.

Using shared memory in SmartHeap for Win32

Beginning in version 3.1, SmartHeap supports Windows 95 and Windows NT shared memory.Ê SmartHeap uses memory mapped files to implement shared memory pools.Ê All of the SmartHeap allocation APIs that accept a memory pool parameter, including MemAllocPtr, MemAllocFS, MemAlloc, and operator new with the placement syntax, support Win32 shared memory.

To create shared memory pools in Win95 or NT, use MemPoolInitNamedShared or MemPoolInitNamedSharedEx.Ê You must specify both the name and size parameters as non-zero.Ê

áÊÊÊÊÊ The name parameter is passed through to CreateFileMapping.Ê It can contain any characters but backslash (\).Ê

áÊÊÊÊÊ The size parameter is used to reserve address space for the memory pool.Ê The memory pool cannot grow larger than this size, but SmartHeap will commit memory to the shared pool based on allocation requests.Ê Therefore, you should specify a size that is the maximum (high water mark) memory requirement for the pool.Ê SmartHeap will commit only as much physical memory as you allocate from the pool regardless of the size parameter you specify.Ê Nevertheless, you should not specify an excessively large size parameter, or you will waste address space.Ê This is particularly important in Win95, where shared memory address space is common to all processes.Ê To help in choosing a suitable size value, you can use MemPoolSize to determine the total memory actually consumed by a memory pool at any time.

Once youâve created a shared memory pool, you can call MemPoolAttachShared from other processes, specifying the same name you previously supplied to MemPoolInitNamedShared[Ex].Ê If you donât know which of your processes will create and which will attach to a shared pool, you can call MemPoolInitNamedShared[Ex] from each process, specifying the same name in each call.Ê If a shared pool of the given name already exists, MemPoolInitNamedShared[Ex] will attach to and return that pool.Ê In this case, the other parameters to MemPoolInitNamedShared[Ex] are ignored.

Mapping shared memory pools to the same address in each process

Because SmartHeap allocation APIs return direct pointers to memory, SmartHeap requires shared memory pools to be mapped to the same address in each process.Ê In Windows 95, this is not a problem since shared memory is always mapped to the same address in each process.Ê NT, however, does not guarantee that shared memory is mapped to the same address in each process.Ê If you create a shared pool in one process and call MemPoolAttachShared in another process in which the address of the memory pool is unavailable, MemPoolAttachShared will fail (it will return NULL after reporting a MEM_OUT_OF_MEMORY error).

To solve this problem, SmartHeap 3.1 includes a new API, MemPoolInitNamedSharedEx.Ê This API lets you specify the address at which a shared memory pool should be mapped (addr) and/or an array of process IDs that will access the shared pool (pids).Ê If you specify a non-NULL value for pids, SmartHeap will search the address space of each of these processes to find a suitable address that is available in all of the processes.

MemPoolInitNamedSharedEx also lets you specify security Win32 attributes for the shared pool.Ê The security parameter you specify is passed through to CreateFileMapping.

In choosing the addr parameter, you should examine the DLLs in each process that will use the shared pool, and find an address space location that is available in each process.Ê You should use MemPoolAttachShared as early as possible during process initialization to ensure that the address range you selected is not used by a call to VirtualAlloc.

If you specify addr as NULL, SmartHeap chooses a random address in the upper half of the application address space for NT, or a random address in the shared memory address space for Win95.Ê This minimizes the chance of collisions with other shared pools or VirtualAlloc objects (which are normally allocated from the beginning of the address space).

If all of the processes that will share a memory pool are running at the time you create the memory pool, you can have SmartHeap find an address automatically by specifying pidCount and pids parameters.Ê In this case, the shared pool will be mapped into each processâs address space before the MemPoolInitNamedSharedEx call returns.Ê If there is no address space region of suitable size available in every process, MemPoolInitNamedSharedEx will fail (this would be very unusual considering that each process has 2 GB of address space).

If youâve specified a pids array to MemPoolInitNamedSharedEx, and if youâre running on NT, and if youâre using the SmartHeap DLL, then when you call MemPoolAttachShared from one of the processes that you previously specified to MemPoolInitNamedSharedEx, you may specify the return value of MemPoolInitNamedSharedEx as the pool parameter along with a NULL name parameter.Ê This is the only case where the name parameter of MemPoolAttachShared is optional in the Win32 SmartHeap implementation.Ê You may also specify both name and pool parameters as non-NULL, or just the name parameter as non-NULL if you wish.Ê For Win95 compatibility, the name parameter must always be specified as non-NULL.

CautionÊ The address-space searching feature of MemPoolInitNamedSharedEx is implemented fully only in the DLL version of SmartHeap (both Debug and Runtime).Ê In the DLL version (shdw32m.lib), MemPoolInitNamedSharedEx will cause the new pool to be mapped into each specified process before the call returns, which guarantees that the pool can be shared between the given processes.Ê In the statically linked version of SmartHeap (shlw32m.lib), MemPoolInitNamedSharedEx searches each specified process and reserves space at a suitable address region, but does not actually map the pool into the other processes during the call to MemPoolInitNamedSharedEx.Ê If the chosen address region becomes unavailable in a given process before MemPoolAttachShared is called in that process, then MemPoolAttachShared will fail.Ê Therefore, to guarantee that a set of processes will be able to successfully share a memory pool in NT, you must use the DLL version of SmartHeap (shdw32m[t].lib).

Miscellaneous details

Shared memory pools are always serialized with inter-process synchronization mutual exclusion.Ê You can concurrently allocate blocks from a shared pool from multiple processes with complete safety.

You can use all of the SmartHeap allocation and de-allocation APIs with shared memory pools.Ê In Debug SmartHeap, shared memory pools fully support all of the same debugging facilities as private memory pools.

If SmartHeap detects an error such an overwrite in a shared pool, the error is reported to the process in which the error is detected, regardless of where the shared memory pool was created.Ê Debug SmartHeap error reports in Win32 include the ID of both the thread and the process where the error wasÊ detected, as well as the thread/process IDs where the erroneous object was created.

In Debug SmartHeap, when you compile your source files with MEM_DEBUG, SmartHeap stores a pointer to the source file name in each allocated memory block.Ê The actual file name is a string constant, generated by the compiler, that exists only in the private address space of the process.Ê For shared memory pools, SmartHeap copies file name strings into space owned by the shared memory pool, so the file names are accessible from all processes that attach to the pool.Ê Only the first 19 characters of file names are stored, so if you allocate shared memory from source files having longer names, the file names reported in memory error reports will be truncated to the first 19 characters.

To end access to a shared pool from a given process, call MemPoolFree from that process.Ê The shared pool will continue to exist until every process that has access to it calls MemPoolFree.Ê The process that creates a shared pool does not need to be the last process to call MemPoolFree; shared pools are not owned by a particular process.

See also ¤2.4.5, ãShared memory,ä and the entries for MemPoolInitRegion, MemPoolInitNamedShared, MemPoolInitNamedSharedEx, and MemPoolAttachShared in ¤4.2, ãFunction reference,ä in the SmartHeap Programmerâs Guide.

SmartHeapâs automatic DLL patching

NoteÊ You can skip this section if you statically link SmartHeap.Ê Only the SmartHeap DLL does any patching of DLLs.

When you link with the DLL version of SmartHeap, SmartHeap automatically patches heap routines in compiler DLLs, such as the C runtime and MFC DLLs.Ê If youâre using MFC, OWL, or other DLLs that share heap memory with their client EXE, this patching is required to ensure that objects allocated in these DLLs can be safely freed by your applicationâs EXE.

NoteÊ SmartHeap ãpatchingä does not affect the on-disk copy of any DLLs, and it does not affect other applications that use the DLLs that SmartHeap patches.Ê SmartHeap modifies only the in-memory copy of the DLL that is private to your applicationâs process.Ê Runtime SmartHeap patches only those DLLs in your process that export heap APIs such as malloc or new.Ê Debug SmartHeap also patches all DLLs that have PDB debug information and that contain statically linked heap API definitions.

In some cases, you may want to disable SmartHeapâs patching of compiler DLLs.Ê You can selectively or globally disable SmartHeapâs patching by adding values to the registry or by adding an API definition to your EXE or DLL.Ê These two techniques are described in the following two sections.

Controlling patching via the registry

You can disable patching either for all of the DLLs in your application or for selected DLLs by adding keys to the Windows NT or Windows 95 registry, as described in the following procedures.Ê You can add registry keys in either of two ways:

áÊÊÊÊÊ Use the Registry Editor (regedt32.exe on NT, regedit.exe on Win95) to add these registry entries manually.

áÊÊÊÊÊ Use the Win32 registry API to add registry keys and values programmatically.Ê This is the method you should use if your application uses the Runtime SmartHeap DLL and you donât want SmartHeap to patch one or more of the DLLs used by your application.

Important!Ê If youâre using MFC, OWL, or other DLLs that share heap memory with their client EXE, do not disable patching for those DLLs, or you may encounter incompatibilities and unexpected GPFs.

NoteÊ SmartHeap stores its settings under the HKEY_LOCAL_MACHINE registry key for compatibility with NT services.Ê Previous SmartHeap releases (version 3.01 and earlier) stored these settings in HKEY_CURRENT_USER.

¯ To disable SmartHeap patching for all DLLs:

1.ÊÊ Add the following key to the Windows NT or Windows 95 registry:

For Runtime SmartHeap, add the registry key:

HKEY_LOCAL_MACHINE\Software\MicroQuill\
SmartHeap\Apps\<app-name>

For Debug SmartHeap, add the registry key:

HKEY_LOCAL_MACHINE\Software\MicroQuill\
HeapAgent\Apps\<app-name>

where <app-name> is the full path of your applicationâs EXE.

Important!Ê Use forward slashes (/) as directory delimiters.Ê Backslash characters (\) are not legal in registry keys.Ê

For example, if your applicationâs full path is c:\apps\foo.exe and you want to disable patching for Runtime SmartHeap, youâd add the registry key:

HKEY_LOCAL_MACHINE\Software\MicroQuill\
SmartHeap\Apps\c:/apps/foo.exe

2.ÊÊ At the Runtime SmartHeap or Debug SmartHeap registry key that you added in step 1, add an entry with the following values:

áÊÊÊÊÊ Value name:Ê PatchProcessOn

áÊÊÊÊÊ Data type:Ê REG_DWORD

áÊÊÊÊÊ Value:Ê 0 (zero).Ê Zero means SmartHeap should not patch DLLs, and a non-zero value means that SmartHeap should patch DLLs.

¯ To disable patching in certain DLLs in your application but not in the entire process:

1.ÊÊ Add the following key and value to the Windows NT or Windows 95 registry:

For Runtime SmartHeap, add the registry key:

HKEY_LOCAL_MACHINE\Software\MicroQuill\
SmartHeap\Apps\<app-name>\SkipDLLs

For Debug SmartHeap, add the registry key:

HKEY_LOCAL_MACHINE\Software\MicroQuill\
HeapAgent\Apps\<app-name>\SkipDLLs

Alternatively, if youâre using Debug SmartHeap with more than one application, or if youâre running your application from more than one directory, you can use the following registry key to have Debug SmartHeap skip DLLs in all applications you use with Debug SmartHeap:

HKEY_LOCAL_MACHINE\Software\MicroQuill\
HeapAgent\SkipDLLs

2.ÊÊ At the Runtime SmartHeap or Debug SmartHeap registry key that you added in step 1, add DLLs that you do not want SmartHeap to patch.Ê For each DLL you want SmartHeap to skip (that is, not patch), add an entry with the following values:

áÊÊÊÊÊ Value name:Ê File<n> where <n> is 0 (zero) for the first DLL you add, 1 (one) for the second, and so on

áÊÊÊÊÊ Data type:Ê REG_SZ

áÊÊÊÊÊ Value:Ê the DLL name (not the full path of the DLL ÷ just file name and extension)

3.ÊÊ To the same registry key, add another entry with the following values:

áÊÊÊÊÊ Value name:Ê FileCount

áÊÊÊÊÊ Data type:Ê REG_DWORD

áÊÊÊÊÊ Value:Ê the number of DLLs youâve added to the registry key

For example, if you want to skip patching DLLs foo.dll and bar.dll, youâd add the following three registry values to the Runtime SmartHeap or Debug SmartHeap registry, as appropriate:

áÊÊÊÊÊ Name File0, type REG_SZ, value foo.dll

áÊÊÊÊÊ Name File1, type REG_SZ, value bar.dll

áÊÊÊÊÊ Name FileCount, type REG_DWORD, value 2

Optionally, the SmartHeap DLL can patch calls to the system heap APIs LocalAlloc, GlobalAlloc, and HeapAlloc with faster SmartHeap equivalents.Ê These APIs are replaced on Windows NT only, not on Windows 95. Beginning in SmartHeap 4.0, patching of system heap APIs is disabled by default.

¯ To enable SmartHeap patching of system heap APIs:

1.ÊÊ Add the Runtime SmartHeap or Debug SmartHeap registry key as described in step 1 of ãTo disable SmartHeap patching for all DLLsä above.

2.ÊÊÊ At the registry key that you added in step 1, add an entry with the following values:

áÊÊÊÊÊ Value name:Ê PatchSystemAllocsOn

áÊÊÊÊÊ Data type:Ê REG_DWORD

áÊÊÊÊÊ Value:Ê 1 (one).Ê A non-zero value means SmartHeap shouldÊ patch system heap APIs, and a zero value means that SmartHeap should not patch system APIs.

When you load a Debug SmartHeap application and Debug SmartHeap encounters DLLs it does not recognize and that do not have either PDB debugging information or exports of heap APIs, Debug SmartHeap will prompt you with the following message:

HeapAgent is unable to find memory allocation function symbols in module <unknown.dll>. Do you want to add <unknown.dll> to the list of DLLs HeapAgent skips in subsequent loads (choose ãYesä only if this DLL does not share the heap with your EXE or other DLLs)?

If you choose the Yes button, Debug SmartHeap adds the DLL name to the registry entry HKEY_LOCAL_MACHINE\Software\
MicroQuill\HeapAgent\SkipDLLs, so this DLL will be skipped whenever Debug SmartHeap encounters it in any application.

¯ To trace SmartHeap patching activity to a log file:

1.ÊÊ Add the Runtime SmartHeap or Debug SmartHeap registry key as described in step 1 of ãTo disable SmartHeap patching for all DLLs,ä above.

2.ÊÊÊ At the registry key that you added in step 1, add an entry with the following values:

áÊÊÊÊÊ Value name:Ê PatchTraceFile

áÊÊÊÊÊ Data type:Ê REG_SZ

áÊÊÊÊÊ Value:Ê The full path of a file name to which SmartHeap will log all patching activity.Ê SmartHeap will create the file if it does not exist.

First-chance exceptions reported by your debugger

When you run your application under both SmartHeap and your source debugger at the same time, your debugger may report one or more first-chance exceptions in the Debug SmartHeap DLL, ha312w32.dll.Ê These exceptions are caused by SmartHeapâs address validation, which uses Win32 structured-exception handling.Ê The exceptions are handled by SmartHeap and are not errors in your application or in SmartHeap.

SmartHeap for Win32 calling convention

In SmartHeap versions 2.0 and 2.1 for Win32, APIs were defined with the __cdecl calling convention.Ê SmartHeap 2.2 and higher uses __stdcall calling convention to define its APIs, which is the calling convention used for the Windows NT and Windows 95 system DLLs.

SmartHeap Win32öspecific values

The following are some platform-specific defaults and attributes for the Win32 version of SmartHeap (all values in bytes, non-debug version of SmartHeap; all values subject to change in future versions):

DescriptionÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ IntelÊÊÊ Alpha Related API, if any

Default page sizeÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ 64KÊÊÊÊÊÊ 64KÊÊÊÊÊÊ MemPoolSetPageSize

Default ãsmallä block thresholdÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ 256ÊÊÊÊÊÊÊ 256ÊÊÊÊÊÊÊ MemPoolSetSmallBlockSize

Per-alloc overhead, FS blocksÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ 0ÊÊÊÊÊÊÊÊÊÊÊ 0ÊÊÊÊÊÊÊÊÊÊÊ MemAllocFS

Per-alloc overhead, ãsmallä blocksÊÊÊÊÊÊÊÊÊÊÊÊÊÊ 0ÊÊÊÊÊÊÊÊÊÊÊ 0ÊÊÊÊÊÊÊÊÊÊÊ malloc, new, MemAllocPtr

Per-alloc overhead, var ptr blocksÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ 2ÊÊÊÊÊÊÊÊÊÊÊ 2ÊÊÊÊÊÊÊÊÊÊÊ malloc, new, MemAllocPtr

Per-alloc overhead, var handle blocksÊÊÊÊÊÊÊÊÊ 14ÊÊÊÊÊÊÊÊÊ 14ÊÊÊÊÊÊÊÊÊ MemAlloc

Granularity, all block typesÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ 4ÊÊÊÊÊÊÊÊÊÊÊ 8ÊÊÊÊÊÊÊÊÊÊÊ all

Minimum block size, FS blocksÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ 4ÊÊÊÊÊÊÊÊÊÊÊ 8ÊÊÊÊÊÊÊÊÊÊÊ MemAllocFS

Minimum block size, ãsmallä blocksÊÊÊÊÊÊÊÊÊÊÊÊ 4ÊÊÊÊÊÊÊÊÊÊÊ 8ÊÊÊÊÊÊÊÊÊÊÊ malloc, new, MemAllocPtr

Minimum block size, all othersÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ 14ÊÊÊÊÊÊÊÊÊ 14ÊÊÊÊÊÊÊÊÊ malloc, new, MemAllocPtr,
ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ MemAlloc

Per-page overhead, all APIsÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ 40ÊÊÊÊÊÊÊÊÊ 40

Minimum page sizeÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ 64KÊÊÊÊÊÊ 64KÊÊÊÊÊÊ MemPoolSetPageSize

Maximum page sizeÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ 64KÊÊÊÊÊÊ 64KÊÊÊÊÊÊ MemPoolSetPageSize

Size of empty memory poolÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ 64KÊÊÊÊÊÊ 64KÊÊÊÊÊÊ MemPoolInit[FS]

Default error handling in Win32

The default error handler in the Windows version of Runtime SmartHeap uses a task-modal message box (see MemDefaultErrorHandler in ¤4.2, ãFunction referenceä in the SmartHeap Programmerâs Guide).Ê If there is insufficient memory to display a task-modal message box, a system modal message box is displayed.

For non-recoverable errors, the default error handler shows an OK button and a Cancel button on the message box.Ê For recoverable errors, Abort, Retry, and Ignore buttons are shown.

Choosing either the Cancel or Abort button causes an int 3 (breakpoint interrupt) to be executed, which will stop in the debugger if a debugger is currently running.Ê If no debugger is running, SmartHeap will call the abort function, which terminates the current task.

Choosing either OK or Ignore causes the SmartHeap function that reported the error to return with an error return value.Ê Choosing Retry causes SmartHeap to retry the operation (for example, memory allocation).

In Debug SmartHeap, an Error Report dialog box is displayed if DBGMEM_OUTPUT_PROMPT is supplied to dbgMemSetDefaultErrorOutput (it is by default).Ê The Debug SmartHeap Error Report dialog box contains the following buttons:

áÊÊÊÊÊ Debug breaks to your source debugger, or if youâre not currently running under a debugger, this button opens the current Win32 ãjust-in-timeä debugger if you have installed one.

áÊÊÊÊÊ Continue resumes execution of your application.

áÊÊÊÊÊ Retry retries the failed operation -- this button is enabled only for out-of-memory errors.

áÊÊÊÊÊ Terminate closes your application.

áÊÊÊÊÊ The remaining buttons on the error report dialog box are available only if you have installed SmartHeapâs sister product, HeapAgent.Ê HeapAgent provides a graphical user interface for controlling heap debugging settings and diagnosing heap errors.Ê If you have HeapAgent, these buttons are used to open HeapAgent browsers, suppress errors, or get online help about a particular error.

If DBGMEM_OUTPUT_CONSOLE is supplied to dbgMemSetDefaultErrorOutput, output is sent to the OutputDebugString Win32 API, and will be displayed in the output window of the active debugger.Ê DBGMEM_OUTPUT_BEEP causes a MessageBeep on errors.