Welcome to SmartHeap! SmartHeap is a professional memory management and debugging library. SmartHeap is a portable implementation with the dual goals of offering the best possible performance for memory management and the most comprehensive heap error detection.
The following are some of SmartHeap’s features:
An implementation that is portable across all major computer architectures and hardware platforms.
Significant speed improvements, especially for large heaps in the presence of virtual memory. SmartHeap outperforms all known compiler malloc implementations.
A Debug version of SmartHeap that detects many new errors and reports more detailed information than prior versions, including the source file, line, and pass count.
Hybrid memory pools that allow both fixed- and variable-size allocations from one pool — malloc now automatically allocates small blocks using the fast fixed-size allocator.
Tuning APIs that allow greater control of resource consumption and swapping performance.
Fully thread-enabled and thread-reentrant on platforms that support multi-threading.
Shared memory support.
More memory and address space is returned to the OS when no longer in use, and several new “tuning APIs” have been added to give additional controls over when memory is returned and how much is returned.
SmartHeap/SMP scaling is improved, particularly on higher processor counts. SmartHeap/SMP scales linearly up to 64 processors. Performance of the SmartHeap multithreaded runtime libs is also improved.
The handle-based API (MemAlloc) is no longer supported, which makes some additional SMP speed optimizations possible. There is a new API, MemAllocAligned, introduced primarily for the benefit of UNIX valloc and memalign.
SmartHeap for Win32 fully supports the Visual Studio .NET compilers in unmanaged C/C++ projects..
SmartHeap 6 offers better absolute speed and better memory utilization. Unlike SmartHeap 5, it returns memory to the OS, and the user can control both how much is returned and when it is returned.
Several new tuning APIs are introduced in this release:
void MemProcessSetFreeBytes(unsigned long bytes) controls how much free space SmartHeap maintains in the large block heap.
void MemProcessSetLargeBlockThreshold(unsigned long bytes) controls the block size SmartHeap manages in its large block heap.
unsigned long MemPoolSetFreeBytes(MEM_POOL pool) controls free space in a pool just as MemProcessSetFreeBytes controls free space in the large block heap.
For more information on these APIs see Chapter 4.
This releases introduces an improved small-block allocator. It 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.
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, and less operating system heap and address space fragmentation.
The thread-enabling optimization described above is disabled if multiple processors are detected. If your application targets SMP systems, it would perform best with our separate SmartHeap for SMP product that is optimized expressly for SMP systems.
SmartHeap is a dynamic memory manager that efficiently allocates and manages dynamic memory. Though most applications require large numbers of small memory blocks to implement dynamic data structures such as linked lists, few, if any, compiler malloc or operator new implementations provide an optimum allocator for this purpose. There are several reasons for this:
First, the malloc API specified by ANSI is so general purpose that it cannot possibly be efficient for all memory allocation requirements. It must handle blocks of all sizes. It must satisfy all application allocation requests from a single memory pool, offering no hope for locality of reference. No standard tuning facilities are defined to optimize for working set size, block size, or allocation patterns.
Second, the allocation algorithms used by virtually all compiler malloc implementations were conceived for physical memory environments. Yet all modern operating systems are virtual memory environments where paging or swapping behavior affects performance more than any other factor in the system. In fact, among the dozens of compiler malloc implementations we have studied, not a single one scales well to very large heap sizes that exceed available physical memory in a virtual memory environment.
Finally, compiler malloc implementations offer limited or non-existent heap error detection. Memory errors are the most common type of bug in C and C++ applications, as well as being the most elusive.
SmartHeap addresses all of these issues by providing a portable implementation that scales extremely well to the largest heap sizes, even in physical-memory constrained environments. SmartHeap offers a wide range of allocation APIs for different requirements, and numerous tuning facilities for squeezing the most performance out of the operating system.
In addition, SmartHeap provides a Debug library that includes a comprehensive array of heap error detection and reporting facilities.
Most applications use a great deal of dynamic memory these days. As the trend towards larger applications continues, applications will put even greater demands on the heap manager. At the same time, memory bugs will become increasingly hard to track down as application complexity continues to rise.
Another trend that magnifies the importance of efficient heap management is the increasing popularity of C++. C++ programs by their nature use dynamic memory much more heavily than their C counterparts, and often for many very small, short-lived allocations.
SmartHeap is specifically designed to handle these kinds of industrial-strength applications that exceed the design capacities of the memory manager built into their compilers. But any application that uses dynamic memory will benefit from SmartHeap’s improved performance and memory utilization.
Moreover, any programmer frustrated by memory errors will benefit from SmartHeap’s simple yet powerful and comprehensive error detection facility.
This manual explains how to use SmartHeap for memory management in your application. It assumes that you are an experienced C or C++ programmer.
The following are brief descriptions of the chapters of this manual:
Chapter 1 Introduction explains what SmartHeap is and who it can benefit. This chapter also includes notational conventions and information on reaching our technical support staff.
Chapter 2 Using SmartHeap tells you how to install and use SmartHeap. This chapter discusses SmartHeap allocators, memory pools, and runtime error handling.
Chapter 3 Debug SmartHeap discusses the Debug version of SmartHeap. This chapter covers the debugging error detection facilities. It includes techniques for isolating numerous common memory bugs.
Chapter 4 Reference provides detailed information on each SmartHeap API. The APIs are first listed by functional category, then the detailed syntax and description of each function is presented alphabetically.
Appendix A Updating from previous versions of SmartHeap discusses the important differences between SmartHeap versions 2.0, 2.1, 2.2, 3.0, 3.1, and 3.2.
Appendix B Common questions/troubleshooting provides suggestions on troubleshooting common memory problems and on resolving the problems that our technical support staff hears about most frequently.
Appendix C Guidelines for evaluating SmartHeap performance provides some suggestions for evaluating SmartHeap performance and some guidelines for benchmarking memory managers.
Glossary Glossary defines the terms used in this manual.
The following notational conventions are used throughout this manual:
Courier font The typeface shown at left is used for all code or for any text that you enter at the command line, exactly as written. For instance, function names, literals, file names, and program examples are in this typeface.
Italics Italics are used as place holders for names (of variables, types, and so on) that you supply.
[ ] Square brackets indicate optional items in a sample command line or in an API syntax listing. Enter only the text between the brackets (assuming you want to supply the optional item); don’t enter the brackets themselves.
... An ellipsis indicates missing code. It appears in some of the examples as an indication that you’d typically insert code here.
Caution! Indicates information that could have unexpected results or cause loss of data. If you don’t understand and follow the accompanying instructions, you may encounter errors in your application.
Important! Indicates information that you may not be aware of, but that is required for a procedure or API to work correctly.
Note Indicates special considerations, tips, or other noteworthy information related to the topic at hand.
Windows 16-bit Indicates information specific to 16-bit Windows.
Before you call Technical Support, please check Appendix B, “Common questions and troubleshooting,” to see if the information you need appears there.
Our technical support staff is available Monday through Friday from 8:00 a.m. to 5:00 p.m., Pacific time. If you’d like assistance or if you have any comments, you can call, fax, or email us:
Phone: 425-827-7200
Fax: 425-650-7150
Internet: support@microquill.com
If you’d like assistance, please provide the following information:
Configuration information on your computer, including operating system/version, processor, amount of memory, size of the swap file, and the size of RAM drives, if any.
The compiler and version you’re using.
Whether your application is written in C or in C++.
Whether you’re linking SmartHeap with an EXE or a DLL.
The version number of SmartHeap you’re working with.
Whether you’re linking with the Debug or Runtime SmartHeap Library.
The exact compiler and linker options you used to compile the application that you’re linking with SmartHeap.
What you’re trying to do and what’s happening instead. Please write down the exact text of any error messages.
A small, reproducible test case that demonstrates the problem, if possible.
SmartHeap
Programmer’s Guide