Contents

New in SmartHeap 5.0............................................................................. ÊÊÊÊÊÊÊÊÊ 1

Improved SMP design................................................................................ ÊÊÊÊÊÊÊÊÊÊÊÊÊ 1

Reduced space overhead........................................................................... ÊÊÊÊÊÊÊÊÊÊÊÊÊ 1

New small-block allocator........................................................................... ÊÊÊÊÊÊÊÊÊÊÊÊÊ 2

New API to control process heap growth............................................... ÊÊÊÊÊÊÊÊÊÊÊÊÊ 2

Installing SmartHeap................................................................................ ÊÊÊÊÊÊÊÊÊ 3

Files in the Solaris SmartHeap release...................................................... ÊÊÊÊÊÊÊÊÊÊÊÊÊ 4

Using SmartHeap with Solaris.............................................................. ÊÊÊÊÊÊÊÊÊ 6

Getting started with the SmartHeap runtime library............................... ÊÊÊÊÊÊÊÊÊÊÊÊÊ 6

Adding the SmartHeap header file to your source files................. ÊÊÊÊÊÊÊÊÊÊÊÊÊ 6

Specifying the location of SmartHeap files...................................... ÊÊÊÊÊÊÊÊÊÊÊÊÊ 7

Linking with Runtime SmartHeap...................................................... ÊÊÊÊÊÊÊÊÊÊÊÊÊ 8

Debugging an application with SmartHeap............................................. ÊÊÊÊÊÊÊÊÊÊÊÊÊ 9

Adding the Debug SmartHeap header file
to your source files.......................................................................... ÊÊÊÊÊÊÊÊÊÊÊÊÊ 9

Specifying the location of SmartHeap files.................................... ÊÊÊÊÊÊÊÊÊÊÊ 10

Recompiling with Debug SmartHeap.............................................. ÊÊÊÊÊÊÊÊÊÊÊ 11

Using SmartHeap with other compilers............................................ ÊÊÊÊÊÊÊ 12

SmartHeap Solaris platform notes..................................................... ÊÊÊÊÊÊÊ 14

Compiler functions that SmartHeap overrides...................................... ÊÊÊÊÊÊÊÊÊÊÊ 14

Multi-threading in Solaris......................................................................... ÊÊÊÊÊÊÊÊÊÊÊ 14

SPARC 9 optimization............................................................................... ÊÊÊÊÊÊÊÊÊÊÊ 15

Using SmartHeap with dynamically-loaded
shared libraries....................................................................................... ÊÊÊÊÊÊÊÊÊÊÊ 16

Using shared memory in SmartHeap for Solaris.................................... ÊÊÊÊÊÊÊÊÊÊÊ 16

Creating heaps in user-supplied regions............................................... ÊÊÊÊÊÊÊÊÊÊÊ 18

SmartHeap Solaris-specific values.......................................................... ÊÊÊÊÊÊÊÊÊÊÊ 19

Default error handling for Solaris............................................................ ÊÊÊÊÊÊÊÊÊÊÊ 19

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.

Reduced space overhead

SmartHeap 5.0 significantly reduces per-block overhead in its UNIX implementations, from 5 bytes to zero bytes for blocks less than 256 bytes in size (and from 9 bytes to zero bytes in 64-bit implementations).Ê Granularity has also been reduced from 8 bytes to 4 bytes.Ê For example, whereas a 12-byte allocation would have consumed 24 bytes in SmartHeap 4.0 (12 + 5 rounded up to next 8-byte multiple), the same 12-byte allocation uses only 12 bytes in SmartHeap 5.0.

Moreover, because SmartHeap 5.0 no longer creates multiple default memory pools for multi-threaded applications, space saving is even greater as multiple threads are able to share the same pages of heap memory in a contention-free manner rather than using separate memory pools.

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.

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 media are not copy protected.Ê To install SmartHeap on your hard disk:

1. Identify the directory you want to install SmartHeap in, create that directory (if necessary) and cd to it.

For example, if you want to install SmartHeap in /opt/sh, enter the following commands:

mkdir /opt/sh

cd /opt/sh

2. Insert the SmartHeap media into your installation device and copy the SmartHeap archive files with the following command:

tar xpvf device_name

where device_name is the name of your installation device (for example, /dev/fd0).

3. Uncompress the SmartHeap files with the following command:

uncompress *.Z

4. Unarchive each file that ends with the .tar extension as follows:

tar xpvf filename.tar

5. Add the SmartHeap include directory to your compilerâs header file search path, and add the SmartHeap lib directory to your linkerâs library search path.

Files in the Solaris SmartHeap release

This SmartHeap release supports Solaris 2.5, 2.6, and 2.7.Ê Included are statically linkable and shared libraries, platform-independent header files, and platform-independent source files for the malloc and C++ operator new definitions.Ê Both single- and multi-thread SmartHeap libraries are included.

The following files are present on the SmartHeap distribution media:

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

libÊÊÊÊÊ libsmartheap_smp.aÊÊÊÊÊÊÊÊÊÊÊ 32-bitÊ runtime SmartHeap/SMP C Solaris archive library

libÊÊÊÊÊ libsmartheapC_smp.aÊÊÊÊÊÊÊÊ 32-bit runtime SmartHeap/SMP C++ Solaris archive library

libÊÊÊÊÊ libsmartheap_smp.soÊÊÊÊÊÊÊÊ 32-bit runtime SmartHeap/SMP Solaris shared library

libÊÊÊÊÊ libsmartheap_mtd.aÊÊÊÊÊÊÊÊÊÊÊ 32-bit multi-thread Debug SmartHeap Solaris C archive library

libÊÊÊÊÊ libsmartheapC_mtd.aÊÊÊÊÊÊÊÊ 32-bit multi-thread Debug SmartHeap C++ Solaris archive library

libÊÊÊÊÊ libsmartheap_mtd.soÊÊÊÊÊÊÊÊ 32-bit multi-thread Debug SmartHeap Solaris shared library

libÊÊÊÊÊ libatomic_ultra.soÊÊÊÊÊÊÊÊÊÊÊ 32-bit SPARC-9 optimization (redistribute with libsmartheap_smp.so for SPARC-9 targets)

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

libÊÊÊÊÊ sysunixinc.oÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ 32-bit object file for pre-SPARC-9 targets (see ãSPARC 9 optimization,ä below)

libÊÊÊÊÊ libsmartheap_smp64.aÊÊÊÊÊÊ 64-bit runtime SmartHeap/SMP C Solaris archive library

libÊÊÊÊÊ libsmartheapC_smp64.aÊÊÊ 64-bit runtime SmartHeap/SMP C++ Solaris archive library

libÊÊÊÊÊ libsmartheap_smp64.soÊÊÊ 64-bit runtime SmartHeap/SMP Solaris shared library

libÊÊÊÊÊ libsmartheap_mtd64.aÊÊÊÊÊÊ 64-bit multi-thread Debug SmartHeap Solaris C archive library

libÊÊÊÊÊ libsmartheapC_mtd64.aÊÊÊ 64-bit multi-thread Debug SmartHeap C++ Solaris archive library

libÊÊÊÊÊ libsmartheap_mtd64.soÊÊÊ 64-bit multi-thread Debug SmartHeap Solaris shared library

Using SmartHeap with Solaris

Hereâs how to get started with SmartHeap on Solaris.

Getting started with the SmartHeap runtime library

Hereâs how you set 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 section.

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

Specifying the location of SmartHeap files

To tell your compiler where to find SmartHeap include and library files:

1. Add the SmartHeap include directory to your compilerâs include path, or specify this directory on the compiler command line, for example:

-I/opt/sh/include

2. Add the SmartHeap lib directory to your linkerâs library path, or specify this directory on the linker command line, for example:

-L/opt/sh/lib

Linking with Runtime SmartHeap

To relink your application with Runtime SmartHeap:

1. Add the Runtime SmartHeap Library after all object files, but before any other libraries, to your linker command line.

If youâre using the SmartHeap
shared library withÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ Link with these libraries

A 32-bit C applicationÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ libsmartheap_smp.so

A 32-bit C++ applicationÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ libsmartheap_smp.so,

ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ LibsmartheapC_smp.a

A 64-bit C applicationÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ libsmartheap_smp64.so

A 64-bit C++ applicationÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ libsmartheap_smp64.so,

ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ LibsmartheapC_smp64.a

If youâre statically linking SmartHeap withÊÊÊÊÊÊÊÊ Link with these libraries

A 32-bit C applicationÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ libsmartheap_smp.a

A 32-bit C++ applicationÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ libsmartheap_smp.a,

A 64-bit C applicationÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ libsmartheap_smp64.a

A 64-bit C++ applicationÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ libsmartheap_smp64.a,

2. Run your make file to relink your application, for example:

make /f myapp.mak

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 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, 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 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):

ÊÊÊÊÊÊ #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 SmartHeap files

To tell your compiler where to find Debug SmartHeap include and library files:

1. Add the SmartHeap include directory to your compilerâs include path, or specify this directory on the compiler command line, for example:

-I/opt/sh/include

2. Add the SmartHeap lib directory to your linkerâs library path, or specify this directory on the linker command line, for example:

-L/opt/sh/lib

Recompiling with Debug SmartHeap

To recompile and relink your application with Debug SmartHeap:

1. Add the following options to your compiler command line:

-DMEM_DEBUG=1 -DDEFINE_NEW_MACRO=1

2. Add the Debug SmartHeap Library before any other libraries, to your linker command line.

If youâre using the SmartHeap
shared library withÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ Link with these libraries

A 32-bit C applicationÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ libsmartheap_mtd.so

A 32-bit C++ applicationÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ libsmartheap_mtd.so,

ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ LibsmartheapC_mtd.a

A 64-bit C applicationÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ libsmartheap_mtd64.so

A 64-bit C++ applicationÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ libsmartheap_mtd64.so,

ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ LibsmartheapC_mtd64.a

If youâre statically linking SmartHeap withÊÊÊÊÊÊÊÊ Link with these libraries

A 32-bit C applicationÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ libsmartheap_mtd.a

A 32-bit C++ applicationÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ libsmartheap_mtd.a,

A 64-bit C applicationÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ libsmartheap_mtd64.a

A 64-bit C++ applicationÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ libsmartheap_mtd64.a,

3. Run your make file to rebuild your application, for example:

make /f myapp.mak

Using SmartHeap with other compilers

If youâre developing your application with a compiler other than the Sun WorkShop 5.0 ANSI C or C++ compiler, and your compiler uses a different name-mangling convention from Sun C++, hereâs how to get started with SmartHeap.

The source code to SmartHeapâs ANSI definitions for malloc, calloc, realloc, and free, and for the new and delete operators, is included with SmartHeap.Ê This allows you to recompile these definitions for use with a non-supported compiler or if you want to customize them for some reason.

NoteÊ The source code for the ANSI C/C++ SmartHeap definitions appears in the source directory in the SmartHeap directory.Ê

If your compiler uses a different C++ name-mangling convention or different operator new/delete semantics than Sun WorkShop 5.0, but you want SmartHeap to define malloc, use the stand SmartHeap C archive or shared library (libsmartheapxxx.a) but not the SmartHeap C++ archive library (libsmartheapCxxx.a).Ê Instead, recompile the source file shnew.cxx with your C++ compiler and link with the resulting object file in addition to the SmartHeap C library.Ê For Runtime SmartHeap, use the following:

CC öc shnew.cxx öo shnew.o

For Debug SmartHeap, use the following:

CC öc öDMEM_DEBUG=1 shnew.cxx öo shnewd.o

To recompile all SmartHeap source files so you can use Runtime SmartHeap with a non-supported compiler:

1. Compile each file in the SmartHeap source directory, except those beginning with ãdbä, which are for Debug SmartHeap only.Ê For example:

cc -c shmalloc.c

2.ÊÊ Compile the SmartHeap source file shmalloc.c a second time, this time with the macro constant MALLOC_MACRO defined on the compiler command line.Ê For example:

cc -c -DMALLOC_MACRO=1 -oshmalmac.o shmalloc.c

3. Create a new library, add all of the object files you compiled in steps 1 and 2, for example:

ar ru myshlib.a shmalloc.o shmalmac.o
ÊÊ defpagsz.o defpool.o defflags.o defsizfs.o

4. Link the resulting library before the regular SmartHeap library on the linker command line when building your application.

You must compile the SmartHeap source files a second time to build a Debug SmartHeap library.Ê To recompile SmartHeap source files so you can use Debug SmartHeap with a non-supported compiler:

1. Compile each file in the SmartHeap source directory with the macro constant MEM_DEBUG defined on the compiler command line, for example:

cc -c -DMEM_DEBUG=1 shmalloc.c

2.ÊÊ Compile the SmartHeap source file shmalloc.c a second time, this time with the macro constant MALLOC_MACRO also defined on the compiler command line.Ê For example:

cc -c -DMEM_DEBUG=1 -DMALLOC_MACRO=1
ÊÊ -oshmalmac.o shmalloc.c

3. Create a new library, add all of the object files you compiled in steps 1 and 2, for example:

ar ru myshlib.a shmalloc.o shmalmac.o shnew.o
ÊÊ defpagsz.o defpool.o defflags.o defsizfs.o
ÊÊ dbgrdfil.o dbgrdsiz.o dbusefil.o dbfrefil.o

4. Link the resulting library before the regular SmartHeap library on the linker command line when building your application.

Important!Ê You must place the SmartHeap Library before any other libraries on your linker command line to ensure that SmartHeap replaces malloc and operator new.

SmartHeap Solaris platform notes

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 in the SmartHeap Programmerâs Guide.

NoteÊ If you do not want SmartHeap to override operator new and delete, simply omit the SmartHeap C++ library (libsmartheapCxxx.a) when linking your application.

If you donât want SmartHeap to override one or more of these functions, you should remove the applicable object module from the SmartHeap libraries.Ê For example, use the following command to prevent SmartHeap from overriding malloc with the statically linked Runtime SmartHeap library:

ar d libsmartheap_smp.a shmalloc.o

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

int SmartHeap_malloc = 0;

Multi-threading in Solaris

The SmartHeap libraries in this release are fully thread-reentrant (MT-safe).Ê If you link SmartHeap with an application that creates multiple threads, make sure to call MemRegisterTask before starting the second thread.Ê

Caution!Ê SmartHeap 5.0 does not initialize its heap mutexes until you call MemRegisterTask.Ê Therefore, if your program does not call MemRegisterTask before creating its second thread, memory allocation calls will not be serialized, which will almost certainly result in heap corruption.Ê

For the SmartHeap/Solaris thread-reentrant libraries, the default memory pool (used by malloc and new) is always serialized, unless you define MemDefaultPoolFlags to disable serialization.Ê Memory pools you create with MemPoolInit[FS] are not serialized unless you supply eitherÊ MEM_POOL_DEFAULT or MEM_POOL_SERIALIZE with the flags parameter.

If you use a given memory pool in only one thread at any time, do not supply MEM_POOL_DEFAULT or MEM_POOL_SERIALIZE when initializing the memory pool, or performance will suffer needlessly.Ê

SPARC 9 optimization

NoteÊ This section applies to 32-bit applications only.Ê

The multi-threaded version of SmartHeap implements a serialization optimization that employs a SPARC 9 instruction.Ê In order to support pre-SPARC 9 targets, we have placed the optimization in a ãfilterä shared library, libatomic_ultra.so.Ê If libatomic_ultra.so is not present at runtime, or if libsmartheap_smp.so is loaded on a pre-SPARC 9 system, SmartHeap will not use the optimization.Ê There is no functional difference with or without libatomic_ultra.so, but the optimization implemented by this shared library significantly impacts performance of multi-threaded applications run on SMP systems.

Important! You should redistribute libatomic_ultra.so if your application targets SPARC 9 systems.Ê

If you statically link with libsmartheap_smp.a, your application will run only on SPARC 9 systems.Ê If you wish to statically link SmartHeap and be compatible with pre-SPARC 9 systems, you must modify libsmartheap_smp.a as follows:

ÊÊ ar d libsmartheap_smp.a atomic.o

ÊÊ ar ru libsmartheap_smp.a sysunixinc.o

NoteÊ You will find sysunixinc.o in the lib directory of the SmartHeap distribution.Ê

Using SmartHeap with dynamically-loaded shared libraries

If you link SmartHeap with a shared library that is dynamically loaded by another application, malloc will most likely already be bound to CRT malloc before your shared library is loaded.Ê As a result, your shared library will call CRT malloc even though it has linked with SmartHeap malloc.

If you are building such as shared library, specify öB symbolic to ld when linking your shared library to ensure that the shared library uses SmartHeap rather than CRT malloc at runtime.

Using shared memory in SmartHeap for Solaris

Beginning in version 3.0, SmartHeap supports UNIX shared memory. SmartHeap uses the shared memory and semaphore facilities of the standard InterProcess Communication (IPC) package to implement shared memory pools.

Use MemPoolInitNamedShared to create shared memory pools.Ê The name parameter to MemPoolInitNamedShared must be a valid shared memory object key, according to UNIX conventions.Ê Use ftok() to create a key, and cast the result to (const char *) when passing to MemPoolInitNamedShared.Ê The flags parameter implicitly includes MEM_POOL_SHARED and MEM_POOL_SERIALIZE, so you do not need to specify these two flags.

The size parameter to MemPoolInitNamedShared specifies the total size of the underlying UNIX shared memory segment.Ê This cannot be resized once the memory pool is created.Ê Specify the total amount of memory you wish to make available to the memory pool.

When determining the pool size, keep in mind that each memory pool requires 4K of space for internal data structures and that free space occupies, on average, one third of the total space in a memory pool.Ê Therefore, if X is the maximum number of bytes you will allocate, specify a pool size of at least X * 2 + 4K.Ê You can use the MemPoolSize function to determine the actual memory in use in a pool, and use this as a guideline for the size parameter.Ê Note that Debug SmartHeap uses more memory than Runtime SmartHeap to store debugging state.

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.

Once a shared memory pool has been created, you can access it from other processes by calling MemPoolAttachShared and specifying the shared pool name.Ê Always pass NULL as the pool parameter for UNIX.

The MemPoolInitNamedShared call must have returned in the original process before MemPoolAttachShared will succeed in another process.Ê The reason for this restriction is that the semaphore that provides for serialization is stored in the shared memory object ÷ there can be no guarantee that the semaphore has been initialized and stored in the shared memory object until the shared memory object itself has been initialized.

You can call MemPoolAttachShared concurrently from as many processesÊ as you like once MemPoolInitNamedShared has returned.

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.

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 current 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; the shared pool is not owned by a particular process.

Creating heaps in user-supplied regions

The SmartHeap API MemPoolInitRegion is now supported in Solaris and other UNIX platforms in SmartHeap 5.0 and higher. MemPoolInitRegion allows you to create a memory pool within a region of memory you supply.

For details about this API, see the entry for MemPoolInitRegion in ¤4.2, ãFunction reference,ä in the SmartHeap Programmerâs Guide.

SmartHeap Solaris-specific values

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

DescriptionÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ 32bitÊ 64bitÊÊÊÊ Related API

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

Default fixed-size block sizeÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ 20ÊÊÊÊÊÊÊ 40ÊÊÊÊÊÊÊÊÊÊÊ MemPoolSetBlockSizeFS

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

Per-alloc overhead, blocks < 256 bytesÊÊÊÊÊÊÊ 0ÊÊÊÊÊÊÊÊÊ 0ÊÊÊÊÊÊÊÊÊÊÊÊÊ MemAllocPtr, malloc, new

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

Per-alloc overhead, var handle blocksÊÊÊÊÊÊÊÊÊ 16ÊÊÊÊÊÊÊ 32ÊÊÊÊÊÊÊÊÊÊÊ MemAlloc

Granularity, FS blocksÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ 8ÊÊÊÊÊÊÊÊÊ 8ÊÊÊÊÊÊÊÊÊÊÊÊÊ MemAllocFS

Granularity, blocks < 256 bytesÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ 4ÊÊÊÊÊÊÊÊÊ 8ÊÊÊÊÊÊÊÊÊÊÊÊÊ MemAllocPtr, malloc, new

Granularity, all othersÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ 8ÊÊÊÊÊÊÊÊÊ 8ÊÊÊÊÊÊÊÊÊÊÊÊÊ MemAllocPtr, MemAlloc

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

Minimum block size, all othersÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ 4ÊÊÊÊÊÊÊÊÊ 8ÊÊÊÊÊÊÊÊÊÊÊÊÊ MemAllocPtr, MemAlloc

Per-page overhead, all APIsÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ 56ÊÊÊÊÊÊÊ 112

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

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

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

Default error handling for Solaris

The default error handler in the Solaris version of SmartHeap prompts with ãAbort, Ignore [, Retry]ä to stderr.Ê Retry is present only for recoverable errors.Ê

If you type:

á ãaä for Abort, SmartHeap calls the abort function, which terminates the application.Ê

á ãiä for Ignore, the SmartHeap function that reported the error returns with an error return value.Ê

á ãrä for Retry, SmartHeap retries the operation (for example, attempts a memory allocation again).