smartheap for smp - microquill software · pdf filesmartheap for smp getting started and...

SmartHeap™ for SMP Getting Started and Platform Guide for

Solaris

Version 8.00

SmartHeap and HeapAgent are trademarks of Compuware Corporation. All other trademarks are the property of their respective holders.

Copyright ©1994-2005 Compuware Corporation. All rights reserved.

Printed September 23, 2005 We’d like to have your ideas and comments about this manual. Your suggestions help us improve our products. Please send comments to:

MicroQuill Software Publishing, Inc. 815 6th Street South, Suite 111 Kirkland, Washington 98033 Voice: (425) 827-7200 Fax: (425) 650-7150 Internet: [email protected]

SmartHeap for SMP Getting Started and Platform Guide — Solaris 3

Contents New in SmartHeap 8.0 ................................................................. 5

Improved performance .......................................................... 5 New API controls thread-specific heap usage....................... 5

New in SmartHeap 7 .................................................................... 6

New in SmartHeap 6 .................................................................... 7 Improved design.................................................................... 7 New tuning APIs ................................................................... 7

Installing SmartHeap ................................................................... 9 Files in the Solaris SmartHeap release ......................................... 10

Using SmartHeap with Solaris.................................................... 12 Getting started with the SmartHeap runtime library (including smp-

debug) ....................................................................................... 12 Adding the SmartHeap header file to your source files ........ 12 Specifying the location of SmartHeap files........................... 12 Linking with Runtime SmartHeap ........................................ 13

Debugging an application with SmartHeap.................................. 14 Adding the Debug SmartHeap header file to source files ..... 14 Specifying the location of SmartHeap files........................... 15 Recompiling with Debug SmartHeap.................................... 16 Using SmartHeap with other compilers ................................ 17

SmartHeap Solaris platform notes............................................. 19 Compiler functions that SmartHeap overrides ...................... 19 Multi-threading in Solaris ..................................................... 19 Using SmartHeap with dynamically-loaded shared libraries 20 Using SmartHeap smp-debug libraries.................................. 20 Using shared memory in SmartHeap for Solaris ................... 20 A note on alignment .............................................................. 22

New in SmartHeap 8.0

4 SmartHeap for SMP Getting Started and Platform Guide — Solaris

Creating heaps in user-supplied regions................................ 22 SmartHeap Solaris-specific values........................................ 23 Default error handling for Solaris ......................................... 23




Improved performance The SmartHeap 8.0 multi-threaded libraries contain performance optimizations making them up to 2x faster than version 7. The performance improvement is greatest on the Windows operating system. Note that the general performance improvements in SmartHeap version 8, and those described under MemDefaultPoolThreadExclusive, below, are available only when running on single-processor (including hyperthread-enabled Intel processor) systems. The performance enhancements are enabled on SMP systems only in the SmartHeap/SMP product.

New API controls thread-specific heap usage SmartHeap 8.0 introduces a new API, MemDefaultPoolThreadExclusive, that can be used to greatly enhance performance and simplify heap object deallocation in applications that use heap exclusively in one or more threads. Applications that will benefit from this new API are those that have one or more heap-intensive threads which exclusively free the memory they allocate. Use MemDefaultPoolThreadExclusive only in threads that exclusively free all heap pointers that are allocated by that thread after the call to MemDefaultPoolThreadExclusive. The new API has the following prototype: MEM_BOOL MemDefaultPoolThreadExclusive(unsigned flags); Specify one of the following values for flags:

• MEM_THREAD_EXCLUSIVE_OFF: default behavior – current thread uses process-wide default memory pool. Heap operations are synchronized with other threads.

• MEM_THREAD_EXCLUSIVE_ON: creates thread-specific default memory pool for the current thread. Synchronization with other threads is not needed, resulting in improved performance. Specify this value only if all allocations created with malloc, calloc, new, or realloc in the calling thread are freed exclusively by the same thread. Can be combined disjunctively with MEM_FREE_ON_THREAD_TERM.

• MEM_FREE_ON_THREAD_TERM: creates thread-specific default memory pool for the current thread. All allocations created in the current thread are automatically freed at thread termination,

New in SmartHeap 7


simplifying and improving performance of storage management. Note that you still must calls delete for objects created with operator new in order for destructors to execute, though you can override operator delete for such objects with an empty operator delete definition if desired (if the objects are used exclusively in thread-specific memory pools) since SmartHeap will automatically free the memory at thread termination. Specify this value only if all allocations created with malloc, calloc, new, or realloc in the calling thread are either not freed or are freed exclusively by the same thread, and if there are no references to allocations created in the calling thread from other threads after the calling thread terminates. Can be combined disjunctively with MEM_THREAD_EXCLUSIVE_ON.

Call this API from each thread where you want one or both of the above behaviors.

New in SmartHeap 7 SmartHeap 7 offers better better memory utilization with little or no performance penalty. More memory and address space is returned to the operating system when no longer in use, and there is a new API (MemProcessUseMunmap) to aggressively return address space on Solaris, DEC UNIX and SGI. The default sub-alloc threshold has been raised from 16K to a little under 64K. This design should use less memory in most cases, particularly when a lot of blocks in the range of 16K to 64K are allocated. A new API (MemPoolSetMaxSubAlloc) you tune the suballoc threshold when appropriate.

New in SmartHeap 6


New in SmartHeap 6

Improved design SmartHeap 6.0 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. A new API is introduced in SmartHeap 6.0 primarily for the benefit of UNIX valloc and memalign. MemAllocAligned (MEM_POOL pool, unsigned long size, unsigned long alignment, unsigned flags) is identical to MemAllocPtr except that the result is aligned to a multiple of the value specified in the “alignment” parameter.

New tuning APIs 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. In SmartHeap 5 this was infinite (memory was never returned to the OS). In SmartHeap 6 the user can control exactly when SmartHeap returns memory to the OS via this API. The default value is 10MB, meaning that SmartHeap won’t start releasing memory to the OS until the large block heap has more than 10MB of free space. Larger values result in better allocation performance but larger process footprint.

• void MemProcessSetLargeBlockThreshold (unsigned long bytes) controls the block size SmartHeap manages in its large block heap. The default size is 512KB. Blocks larger than the threshold value are allocated by the OS and freed directly to the OS. Larger values result in better performance but potentially larger process footprint.

• unsigned long MemPoolSetFreeBytes(MEM_POOL pool, unsigned long bytes) controls free space in a pool just as MemProcessSetFreeBytes controls free space in the large block heap. The default value is 1MB. Large values result in better performance and less contention at the expense of more space for allocations less than 16K in size. When this value is non-zero, SmartHeap leaves empty pages, up to the aggregate size specified, inside the pool. When a pool needs to add a page it can do so

New in SmartHeap 6


without a global lock or a large-block heap allocation by recycling a page previously freed by the same pool.

Installing SmartHeap


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.7, 8, 9 and 10. 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_smpd.a 32-bit runtime SmartHeap smp-debug C Solaris

archive library lib libsmartheapC_smpd.a 32-bit runtime SmartHeap smp-debug C++

Solaris archive library lib libsmartheap_smpd.so 32-bit runtime SmartHeap smp-debug 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



Directory File Description lib libsmartheap_mtd.so 32-bit multi-thread Debug SmartHeap Solaris

shared library 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_smpd64.a 64-bit runtime SmartHeap smp-debug C Solaris

archive library lib libsmartheapC_smpd64.a 64-bit runtime SmartHeap smp-debug C++

Solaris archive library lib libsmartheap_smpd64.so 64-bit runtime SmartHeap smp-debug 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


Using SmartHeap with Solaris Here’s how to get started with SmartHeap on Solaris.

Getting started with the SmartHeap runtime library (including smp-debug) 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, LibsmartheapC_smp.a

A 64-bit C application libsmartheap_smp64.a

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

2. Run your make file to relink your application, for example: make /f myapp.mak

If you’re using the smp debug shared library with Link with these libraries A 32-bit C application libsmartheap_smpd.so

A 32-bit C++ application libsmartheap_smpd.so, LibsmartheapC_smpd.a

A 64-bit C application libsmartheap_smp64d.so



A 64-bit C++ application libsmartheap_smp64d.so, LibsmartheapC_smp64d.a

If you’re statically linking the debug-smp lib with Link with these libraries A 32-bit C application libsmartheap_smpd.a

A 32-bit C++ application libsmartheap_smpd.a, LibsmartheapC_smp.a

A 64-bit C application libsmartheap_smp64d.a

A 64-bit C++ application libsmartheap_smp64d.a, LibsmartheapC_smp64d.a

3. 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, LibsmartheapC_mtd.a

A 64-bit C application libsmartheap_mtd64.a

A 64-bit C++ application libsmartheap_mtd64.a, LibsmartheapC_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 (Forte/SunStudio) 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. Note Although we do not officially support the Gnu gcc compiler, our customers have successfully used it with SmartHeap by following the directions in this getting started guide for linking with the supported Sun compilers. 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.

Compiler functions that SmartHeap overrides


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

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 SmartHeap smp-debug libraries The SmartHeap ‘smp-debug’ libs are useful for detecting heap errors which may only manifest on an smp machine when multiple threads are performing heap operations concurrently. These bugs may not be apparent under other heap managers (crt and debug SmartHeap for example) that serialize heap access. Note that these smp-debug libs are not appropriate for general-purpose debugging; use the regular SmartHeap debug libs instead. To use the debug smp libs, ensure that you have not disabled SmartHeap error reporting (it is enabled by default). Do not define MEM_DEBUG or DEFINE_NEW_MACRO on the compiler command line. If an error is detected, you will get a SmartHeap error report. Note that overwrites will only be detected by a call to MemPoolCheck:

#include "smrtheap.h"

MemPoolCheck(MemDefaultPool);

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

Using shared memory in SmartHeap for Solaris


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

A note on alignment The ANSI standard specifies that malloc and new return memory suitably aligned for any object, but SmartHeap potentially returns non-aligned memory in order to conserve space. Specifically, SmartHeap’s small block allocator (SBA) aligns on a word multiple. The first SBA block in a page is aligned on a double boundary, but subsequent blocks are aligned on a word multiple. So on a 32-bit architecture, a 4-byte SBA request will return 4-byte aligned, but an 8-byte request will return 8-byte aligned memory. Typically, compilers pad structures that contain doubles to a double multiple, so doubles will generally be suitably aligned even with SBA. However, this isn’t guaranteed. In order to guarantee sizeof(double) alignment, you must disable the SBA. SmartHeap’s medium and large blocks always align on double boundaries. To disable the SBA, use the following call: #include <smrtheap.h> MemPoolSetSmallBlockAllocator(MemDefaultPool, MEM_POOL_SMALL_BLOCK_NONE);

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


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

smartheap for smp - microquill software · pdf filesmartheap for smp getting started and...

Documents