New in SmartHeap 5.0

Improved SMP design

SmartHeap 5.0 introduces a new SMP-specific heap design that is both more speed and space efficient than SmartHeap 4.0.Ê SmartHeap 5.0 no longer creates multiple default memory pools for malloc but instead implements contention-free serialization within a single memory pool using a proprietary technique.Ê These changes improve performance even on uni-processor systems because SmartHeap now avoids the operating systemâs slow mutex serialization primitives.

Because multiple pools are no longer needed for optimal SMP performance, all non-shared SmartHeap memory pools created with MEM_POOL_SERIALIZE now provide contention-free SMP heap performance.Ê This means that you can now use all the SmartHeap APIs, including MemPoolInitRegion, for optimal performance on SMP systems.

In SmartHeap 4.0, only the default memory pool (that used by malloc and operator new) implemented any SMP optimization.

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.Ê Hence, 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 introduces 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ÊÊÊÊÊÊÊÊÊÊÊ shsmp.dllÊÊÊÊÊÊÊÊÊÊÊ Runtime SmartHeap dynamic link library.

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

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

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

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

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

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

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 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ÊÊÊÊÊÊÊÊÊÊÊ shdsmpbt.libÊÊÊÊÊÊÊÊÊÊÊ Runtime SmartHeap multi-thread DLL import library for
ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ Borland C++ (Intel only).

borlandÊÊÊÊÊÊÊÊÊÊÊ haw32b.libÊÊÊÊÊÊÊÊÊÊÊ Debug SmartHeap 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 "shmfcsmp.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 shsmp.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\shsmp.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\shsmp.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 multi-threaded app,
without MFC, with statically linked MFC 3.0,
or the MFC 3.0/4.x DLLÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ shdsmpmt.lib

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

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

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

An EXE or DLL in a multi-threaded app,
with statically-linked MFC 4.xÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ shmfc4mt.lib, shlsmpmt.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 (shdsmpmt.lib).Ê If your application links with Debug MFC, you must link with Debug SmartHeap.

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 (shlsmpmt.lib or shdsmpmt.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 (shlsmpmt.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 (shdsmpmt.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 shlsmpmt.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 add the file shdsmpbt.lib in the Add to Project List dialog box.

This file appears 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 (shdsmpbt.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 for SMP is fully thread-reentrant and thread-enabled, meaning that multiple threads calling malloc/free/new/delete can concurrently proceed with no blocking.

NoteÊ It is not necessary to call MemRegisterTask or define MemDefaultPoolFlags 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_SHARED 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 that 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 (shdsmpmt.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 (shlsmpmt.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 (shdsmpmt.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.

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.

¯ 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

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ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ MemPoolSetPageSize

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

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

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

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

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

Granularity, 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ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ malloc, new, MemAllocPtr,
ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ MemAlloc

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

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

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

Size of empty memory poolÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ 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.