If you’re upgrading from a previous version of SmartHeap, please read this appendix for important information about SmartHeap 3.3, 3.2, 3.1, 3.0, 2.2, 2.1, and 2.0.
Note On 16- and 32-bit Windows platforms, SmartHeap 2.21 and later now ships with HeapAgent libraries instead of the Debug SmartHeap libraries. The HeapAgent libraries have the same API as Debug SmartHeap, but the library file naming convention has changed from shdXXXXd.lib to haXXXX.lib. There is a corresponding change in the SmartHeap header files, too. The debug APIs and structures have been moved to heapagnt.h. You can continue including smrtheap.h or smrtheap.hpp in your sources files — the SmartHeap header files now automatically include heapagnt.h if MEM_DEBUG is defined.
The SmartHeap API is source-compatible with previous versions, but it is not binary-compatible. Therefore, do not rename (for example) OPTIMEM.DLL, SMRTHEAP.DLL, SH20W16.DLL, SH21W16.DLL, or SH22W16.DLL to the new SmartHeap DLL name, SH30W16.DLL!
Also, be sure to delete all SmartHeap header files from previous SmartHeap releases before compiling applications with the latest version of SmartHeap.
New features added for SmartHeap 6.0 include:
Better absolute speed and memory utilization. SmartHeap 6 returns memory to the OS.
Better SMP scaling (SmartHeap/SMP only)
A new API, MemProcessSetFreeBytes, controls how much free space SmartHeap maintains in the large block heap
A new API, MemProcessSetLargeBlockThreshold, controls the block size SmartHeap manages in its large block heap.
A new API, MemPoolSetFreeBytes, controls free space in a pool.
New features added for SmartHeap 5.0 include:
An improved small-block allocator incurs zero bytes per allocation of overhead and recycles space more effectively.
Anew API, MemProcessSetGrowIncrement, allows you to control how much memory SmartHeap requests from the operating system when a memory pool needs to grow.
New features added for SmartHeap 4.0 include:
Sparate builds of the SmartHeap library that are optimized for single- and multi-threaded applications, respectively.
A new SmartHeap distribution, SmartHeap for SMP, optimized expressly for SMP systems.
New features added for SmartHeap 3.3 include:
Support for Microsoft Visual C++ 5.0.
A new API, MemPoolInitRegion, for creating memory pools in user-supplied regions of memory. See MemPoolInitRegion in §4.2, “Function reference.”
A new API, MemSetPatching, for programmatically controlling when and where SmartHeap patches heap routines. See MemSetPatching in §4.2, “Function reference.”
New features added for SmartHeap 3.2 include:
Support for Windows NT 4.0 and Microsoft Visual C++ 4.2.
In the Win32 version, dynamically loaded DLLs are patched (in addition to implicitly linked DLLs) so they use the same heap manager as your EXE.
On Windows NT only, system allocation APIs such as HeapAlloc, LocalAlloc, and GlobalAlloc are replaced by SmartHeap in addition to C runtime APIs such as malloc and new.
Optimization of checking in Debug SmartHeap, making Debug SmartHeap allocation performance as much as three times faster than in previous versions.
New features added for SmartHeap 3.1 include:
SmartHeap 3.1 adds shared memory support for Windows 95 and Windows NT. See “Using shared memory in SmartHeap for Win32” in the Getting Started and Platform Guide. See also MemPoolInitNamedSharedEx in §4.2, “Function reference.”
Support for Microsoft Visual C++ version 4.1 in SmartHeap for 32-bit Windows.
Support for Borland C++ version 5.0 in SmartHeap for 32-bit Windows.
A new tuning API, MemPoolSetSmallBlockSize, that establishes the threshold for the small vs. medium-size block allocation algorithms. See MemPoolSetSmallBlockSize in §4.2, “Function reference.”
A new Debug SmartHeap API, dbgMemScheduleChecking, that lets you schedule continuous, incremental heap checking in a background thread (this API is present in SmartHeap 3.01 on Unix platforms). See dbgMemScheduleChecking in §4.2, “Function reference.”
A new handle-based memory API, MemSizeRequested, that returns the requested size of a block, much like GetHandleSize on the Mac. See MemSizeRequested in §4.2, “Function reference.”
New features added for SmartHeap 3.0 include:
SmartHeap 3.0 contains a new allocation algorithm for small blocks (less than 256 bytes) that boosts performance 2x or more over SmartHeap 2.x, as well as reducing per-allocation size overhead.
In Windows NT and Windows 95, SmartHeap 3.0 now automatically patches compiler runtime library (CRT) DLLs, including MFC and OWL DLLs, at runtime, so you no longer have to use rebuilt versions of these compiler DLLs to use SmartHeap with your app.
New APIs were added for multi-threaded platforms, for locking and unlocking a memory pool. MemPoolLock locks a pool for exclusive access by the calling thread until a corresponding MemPoolUnlock.
Many new debugging features have been introduced in Debug SmartHeap, allowing more errors to be detected.
Several new debugging APIs were added: dbgMemCheckPtr, dbgMemCheckAll, dbgMemSetCheckFrequency, dbgMemDeferFreeing, dbgMemSetDeferSizeThreshold, dbgMemSetDeferQueueLen, dbgMemPoolSetDeferQueueLen, dbgMemFreeDeferred, dbgMemPoolSetName, dbgMemReallocMoves, dbgMemSuppressFreeFill, dbgMemReportWrongTask, dbgMemPtrInfo, dbgMemPoolInfo, dbgMemSettingsInfo, dbgMemBreakpoint. See the individual function names in §4.2, “Function reference.”
New features added for SmartHeap 2.2 include:
Shared memory support added for OS/2 2.x and UNIX.
Added support for the Rational DOS/4G DOS Extender.
New features added for SmartHeap 2.1 include:
Many new platforms are now supported, including real mode DOS, 16- and 32-bit DOS and Windows Extenders, OS/2 1.x, Macintosh, Sun, HP UX, and Silicon Graphics. See the Getting Started and Platform Guide.
Multi-threading support added for OS/2 2.x, Windows NT, and HP UX.
New SmartHeap APIs added: MemDefaultPoolFlags, MemErrorUnwind, and MemPoolPreAllocateHandles. See the individual function names in §4.2, “Function reference.”
Support added for Borland C++ 4.0 for 16 bit x86 platforms.
There is one important change in semantics for SmartHeap 2.1 on all platforms:
If you define a memory error handler that does not return (that is, a non-local exit such as longjmp), you must call MemErrorUnwind immediately prior to the non-local exit.
There are a couple of important changes in semantics for the 16 bit Windows version of SmartHeap 2.1:
The SmartHeap 2.1 DLL now requires an explicit call to MemRegisterTask sometime before the first client of the DLL terminates. See §5.1.12, “SmartHeap Windows DLL background monitor EXE,” for details.
If you allocated page-locked memory with a SmartHeap memory pool created with MEM_POOL_VIRTUAL_LOCK, the memory is always allocated from above the one megabyte boundary. This change was requested by SmartHeap 2.0 users. If you need DOS memory for a real-mode interrupt handler, use GlobalDosAlloc.
If you’re updating from SmartHeap version 1.x (or the previous product name, OptiMem), SmartHeap 2.0 includes many new features:
A Debug version of SmartHeap, as distinct from the Runtime version that you distribute with production applications. Debug SmartHeap detects many new types of errors, and reports much more detailed information about the errors it finds. Debug SmartHeap also provides numerous debug-only APIs. See Chapter 3, “Debug SmartHeap,” and also the dbgMemXXX APIs in §4.2, “Function reference.”
Statically linkable libraries in addition to the DLL version of SmartHeap. SmartHeap 2.x can be statically linked into either a DLL or an EXE. See the Getting Started and Platform Guide.
A portable implementation, with binary versions supporting 100% compatible APIs supporting over a dozen platforms. See the Getting Started and Platform Guide.
You can now allocate both fixed-size and variable-size blocks from all memory pools. See MemPoolSetBlockSizeFS in §4.2, “Function reference.”
An improved handle-based allocation API, with double indirection of handles and dual moveable/fixed heaps. See §2.3.7, “Handle-based API.”
New APIs for tuning memory pools. See §2.4.6, “Controlling pool size and growth.”
You can now control whether MemReAlloc and MemReAllocPtr move the block or expand the block in place. See the MEM_RESIZE_IN_PLACE flag of MemReAllocPtr in §4.2, “Function reference.”
The 16 bit Windows DLL version of SmartHeap 2.x automatically unregisters client tasks and DLLs when they terminate, even if their termination was abnormal, for example, due to a GP fault. See §5.1.3 “Using SmartHeap in a 16 bit Windows DLL.”
There are many new SmartHeap APIs, including:
dbgMemFormatCall dbgMemSetGuardSize
dbgMemFormatErrorInfo dbgMemSetInUseFill
dbgMemPoolDeferFreeing MEM_REFERENCE
dbgMemPoolFreeDeferred MemFix
dbgMemPoolSetCheckFrequency MemIsMoveable
dbgMemProtectPtr MemLockCount
dbgMemReportLeakage MemPoolPreAllocate
dbgMemSetCheckpoint MemPoolSetBlockSizeFS
dbgMemSetDefaultErrorOutput MemPoolSetCeiling
dbgMemSetEntryHandler MemPoolSetFloor
dbgMemSetExitHandler MemPoolSetPageSize
dbgMemSetFreeFill MemUnfix
dbgMemSetGuardFill
For more information, see the individual function names in §4.2, “Function reference.”
There are a few important changes in semantics for the 16 bit Windows version of SmartHeap 2.0:
SmartHeap now automatically registers tasks on the first call to MemRegisterTask. Moreover, because the SmartHeap DLL automatically unregisters clients when they terminate, you no longer have to call MemUnregisterTask.
In SmartHeap 2.x, MemRegisterTask registers the current Windows module instance with SmartHeap. If the call to MemRegisterTask is linked into an EXE, SmartHeap registers the current task just as in SmartHeap version 1.x. However, if the call is linked into a DLL, SmartHeap registers the calling DLL itself. This allows each DLL that calls SmartHeap to have its own shared memory, error handlers, and debugging state. The 16 bit Windows DLL version of SmartHeap 2.0 automatically unregisters client tasks and DLLs when they terminate, even if their termination was abnormal, for example, due to a GP fault. See §5.1.3, “Using SmartHeap in a 16 bit Windows DLL,” for more details.
Similarly, when you allocate shared memory or establish an error handler in SmartHeap 2.x, the memory or error handler is actually owned by the Windows module in which the call to MemPoolInit or MemSetErrorHandler is linked. SmartHeap automatically frees such memory when all instances of the owning Windows module (EXE or DLL) terminate. See MemPoolInit and MemSetErrorHandler in §4.2, “Function reference.”
Another difference with MemRegisterTask (on all platforms) is that it increments a registration reference count. MemUnregisterTask decrements the reference count and doesn’t actually terminate the task/DLL/process until the reference count reduces to zero. See MemRegisterTask in §4.2, “Function reference.”
In SmartHeap 2.x, malloc, _fmalloc/farmalloc, and C++ operator new are all overridden by SmartHeap by default. These routines are all statically linked with your application even when you use the SmartHeap DLL (the library shdw16[d].lib is actually a combined import and static link library). You no longer have to compile smrtheap.cpp to define SmartHeap operator new. See §2.3.2, “ANSI C memory API,” §2.3.3, “If you do not want SmartHeap to override malloc,” and §2.3.4, “C++ memory API.”
Both malloc and C++ operator new now allocate from the same default memory pool. See MemDefaultPool in §4.2, “Function reference.”
There are several syntactic differences between the public APIs of SmartHeap 2.0 and previous versions:
MemPoolInit and MemPoolInitFS now accept a flags parameter rather than a boolean bShared parameter. The MEM_POOL_SHARED flag, which specifies shared memory, has the value 1. Therefore, if you currently have calls to MemPoolInit that pass TRUE as defined in WINDOWS.H, these calls will continue to work in SmartHeap 2.x. However, we recommend that you change this parameter value to MEM_POOL_SHARED to be safe. See MemPoolInit in §4.2, “Function reference.”
MemAllocPtr and MemReAllocPtr now accept a flags parameter rather than a boolean bZeroInit parameter. The MEM_ZEROINIT flag, which specifies zero initialization, has the value 1. Therefore, if you currently have calls to MemAllocPtr that pass TRUE as defined in WINDOWS.H, these calls will continue to work in SmartHeap 2.x. However, we recommend that you change this parameter value to MEM_ZEROINIT to be safe. See MemAllocPtr in §4.2, “Function reference.”
The SMRTANSI.H header file, which includes macro versions of malloc, etc., has been renamed to SHMALLOC.H. If you have many source files that include SMRTANSI.H, you can avoid any changes by creating a new file called SMRTANSI.H that includes SHMALLOC.H.
Both the MEM_DEFAULT_POOL macro constant and the C++ static member function MemPool::GetPool() have been replaced by the C global variable MemDefaultPool. In SmartHeap 2.x, malloc, MEM_malloc, etc. are always statically linked into each application that uses SmartHeap rather than being exported from the SmartHeap DLL.
MemSetSafetyLevel is now supported only in Debug SmartHeap. It has therefore been renamed to dbgMemSetSafetyLevel. See dbgMemSetSafetyLevel in §4.2, “Function reference.”
The SmartHeap memory pool type is now a 32 bit value rather than a 16 bit value. As long as you store memory pools in variables of type MEM_POOL and never cast MEM_POOLs to 16 bit types, this change won’t affect you.
Several fields changed in the MEM_POOL_ENTRY structure used by MemPoolWalk. See MemPoolWalk in §4.2, “Function reference.”
Several fields changed in the MEM_POOL_INFO structure used by MemPoolInfo, MemPoolFirst, and MemPoolNext. See MemPoolInfo in §4.2, “Function reference.”
Many fields have been added to the MEM_ERROR_INFO structure passed to error handlers established with MemSetErrorHandler. SmartHeap 1.x identified only the API and a single parameter where the error was detected. The Debug version of SmartHeap 2.x places information in over a dozen additional fields of MEM_ERROR_INFO to help pinpoint the error. See MemSetErrorHandler in §4.2, “Function reference,” for details.
Several new error types have been introduced — see §4.3 “Error codes.”
The APIs MemChainErrorHandler and MemRemoveErrorHandler, just introduced in SmartHeap version 1.52, are no longer supported, since per-DLL error handlers makes these APIs unnecessary. If you currently call MemChainErrorHandler, you should now chain by directly calling the previous error-handling function pointer returned by MemSetErrorHandler. You can simply delete any calls to MemRemoveErrorHandler. See MemSetErrorHandler in §4.2, “Function reference.”
The MemFlags function is no longer supported. SmartHeap 2.x defines MemFlags as a macro that translates to MemLockCount for compatibility. See the new APIs MemLockCount §4.2, “Function reference.”
The API MemPoolSetFreestoreThreshold is no longer supported. Use MemPoolSetCeiling and/or MemPoolSetFloor instead.
Be sure to read the readme.txt (or README) file for additional changes that might not be listed here.
SmartHeap
Programmer’s Guide