SmartHeap Programmer's Guide

Chapter 1: Introduction

New in SmartHeap 7.0

New in SmartHeap 6.0

New in SmartHeap 5.0

SmartHeap for SMP

1.1 What is SmartHeap?

1.2 Who can benefit from SmartHeap?

1.3 About this manual

1.4 Notational conventions

1.5 Reaching Technical Support

Chapter 2: Using SmartHeap

2.1 Installing SmartHeap

2.1.1 SmartHeap files common to all platforms

2.2 Getting started with SmartHeap

2.2.1 SmartHeap header files

2.2.2 Linking with the SmartHeap Library

2.2.3 Memory models supported by SmartHeap

2.2.4 Task registration

2.2.5 Using SmartHeap in multi-threaded applications

2.3 Choosing an allocator for your application

2.3.1 Summary of SmartHeap API choices

2.3.2 ANSI C memory API

2.3.3 If you do not want SmartHeap to override malloc

2.3.4 C++ memory API

2.3.5 Fixed-size API

2.3.6 Pointer-based API

2.3.7 Handle-based API

2.4 Using memory pools

2.4.1 Fixed-size memory pools

2.4.2 Freeing related allocations

2.4.3 Establishing working sets

2.4.4 Controlling fragmentation

2.4.5 Shared memory

2.4.6 Controlling pool size and growth

2.4.7 Statistics

2.5 Runtime error handling

2.5.1 Errors detected by SmartHeap

2.5.2 SmartHeap error handling

2.6 Going to market

Chapter 3: Debug SmartHeap

3.1 About Debug SmartHeap

3.2 Setting up for Debug SmartHeap

3.2.1 Linking for Debug SmartHeap

3.2.2 Compiling for Debug SmartHeap

3.2.3 Recompiling persnickety C++ modules

3.3 Detecting bugs with SmartHeap

3.3.1 Controlling speed vs. safety in Debug SmartHeap

3.3.2 Controlling deferred freeing in Debug SmartHeap

3.3.3 Retrieving SmartHeap debugging information

3.3.4 Preventing bugs

3.3.5 Validating pointers and memory pools

3.3.6 Detecting double freeing

3.3.7 Detecting memory overwrites

3.3.8 Detecting writes into free blocks

3.3.9 Detecting reads of free blocks

3.3.10 Detecting dangling and wild pointers

3.3.11 Detecting unexpected frees and reallocs

3.3.12 Marking data as read-only

3.3.13 Preventing stack scribbling

3.3.14 Detecting leakage (garbage)

3.3.15 Constipation

3.4 Debug error handling

3.4.1 Controlling debug error output

3.4.2 Writing a custom error handler

3.4.3 Tracing SmartHeap calls

3.4.4 Debug SmartHeap error reports

Chapter 4: Reference

4.1 Functions by category

4.1.1 Task registration

4.1.2 Memory pools

4.1.3 ANSI standard C API

4.1.4 C++ API

4.1.5 Pointer-based API

4.1.6 Fixed-size API

4.1.7 Handle-based API

4.1.8 Error handling

4.1.9 Debugging

4.2 Function reference

calloc

dbgMemBreakpoint

dbgMemCheckAll

dbgMemCheckPtr

dbgMemDeferFreeing

dbgMemFormatCall

dbgMemFormatErrorInfo

dbgMemFreeDeferred

dbgMemPoolDeferFreeing

dbgMemPoolFreeDeferred

dbgMemPoolInfo

dbgMemPoolSetCheckFrequency

dbgMemPoolSetDeferQueueLen

dbgMemPoolSetName

dbgMemProtectPtr

dbgMemPtrInfo

dbgMemReallocMoves

dbgMemReportLeakage

dbgMemReportWrongTaskRef (16-bit Windows only)

dbgMemScheduleChecking

dbgMemSetCheckFrequency

dbgMemSetCheckpoint

dbgMemSetDefaultErrorOutput

dbgMemSetDeferQueueLen

dbgMemSetDeferSizeThreshold

dbgMemSetEntryHandler, dbgMemSetExitHandler

dbgMemSetGuardSize, dbgMemGuardSize,
dbgMemSetGuardFill, dbgMemGuardFill,
dbgMemSetFreeFill, dbgMemFreeFill,
dbgMemSetInUseFill, dbgMemInUseFill

dbgMemSetSafetyLevel

dbgMemSettingsInfo

dbgMemSuppressFreeFill

dbgMemTotalCount

dbgMemTotalSize

dbgMemWalkHeap

delete

free

malloc

MemAlloc

MemAllocAligned

MemAllocFS

MemAllocPtr

MemCheckPtr

MemDefaultErrorHandler

MemDefaultPool, MemDefaultPoolBlockSizeFS,
MemDefaultPoolFlags, MemDefaultPoolPageSize, MemInitDefaultPool, MemFreeDefaultPool

MemErrorUnwind

MemFix

MemFree

MemFreeFS

MemFreePtr

MemHandle

MemIsMoveable

MemLock

MemLockCount

MemPoolAttachShared

MemPoolCheck

MemPoolCount

MemPoolFirst

MemPoolFree

MemPoolInfo

MemPoolInit

MemPoolInitFS

MemPoolInitNamedShared

MemPoolInitNamedSharedEx

MemPoolInitRegion

MemPoolLock

MemPoolNext

MemPoolPreAllocate

MemPoolPreAllocateHandles

MemPoolSetBlockSizeFS

MemPoolSetCeiling

MemPoolSetFloor

MemPoolSetFreeBytes

MemPoolSetHighThreads

MemPoolSetMaxSubpools

MemPoolSetPageSize

MemPoolSetSerialization

MemPoolSetSmallBlockAllocator

MemPoolSetSmallBlockSize

MemPoolShrink

MemPoolSize

MemPoolUnlock

MemPoolWalk

MemProcessCoelesceSystemAllocs

MemProcessFlushAll

MemProcessSetFreeBytes

MemProcessSetGrowIncrement

MemProcessSetHeapLimit

MemProcessSetLargeBlockThreshold

MemProcessUseMunmap

MemReAlloc

MemReAllocPtr

MEM_REFERENCE

MemRegisterTask

MemSetErrorHandler

MemSize

MemSizeRequested

MemSizePtr

MemUnfix

MemUnlock

MemUnregisterTask

MemVersion

new

realloc

4.3 Error codes

Appendix A: Updating from previous versions of SmartHeap

Appendix B: Common questions and troubleshooting

B.1 Compiler/linker issues

Borland C++ compiler

Microsoft C/C++ compiler

Watcom C/C++ compiler

Other compilers

B.2 Compatibility with third-party products

Inmark zApp

B.3 Memory bugs

B.4 DLLs (16-bit Windows only)

B.5 C++

B.6 ANSI C (malloc, etc.)

B.7 Macintosh-specific problems

Appendix C: Guidelines for evaluating
SmartHeap performance

C.1 Considerations for evaluating
memory manager performance

C.2 Constructing a realistic test case

C.3 SmartHeap features that maximize performance

C.4 Quick tips for tuning SmartHeap performance

C.5 No performance boost?
Be sure SmartHeap is properly linked in

Glossary

Chapter 1
Introduction

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:

New in SmartHeap 7.0

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..

New in SmartHeap 6.0

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:

For more information on these APIs see Chapter 4.

New in SmartHeap 5.0

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.

SmartHeap for SMP

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.

1.1 What is SmartHeap?

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.

1.2 Who can benefit from SmartHeap?

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.

1.3 About this manual

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.

1.4 Notational conventions

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.

1.5 Reaching Technical Support

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:


SmartHeap Programmer’s Guide 9