Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Thursday, June 13, 2019
 
 

mtmalloc(3MALLOC)

Name

mtmalloc, mallocctl - MT hot memory allocator

Synopsis

cc [ flag ... ] file ... –lmtmalloc [ library ... ]
#include <stdlib.h>

void *malloc(size_t size);
void *calloc(size_t nelem, size_t elsize);
void *memalign(size_t alignment, size_t size);
void *realloc(void *ptr, size_t size);
void *valloc(size_t size);
size_t malloc_usable_size(void *ptr);
void free(void *ptr);
#include <mtmalloc.h>

void mallocctl(int 
cmd, long value);

Description

These functions provide a simple general-purpose memory allocation package that is suitable for use in high performance multithreaded applications. The suggested use of this library is in multithreaded applications; it can be used for single threaded applications, but there is no advantage in doing so. This library cannot be dynamically loaded with dlopen(3C) during runtime because there must be only one manager of the process heap.

They operate as described on the malloc(3C) manual page, except for the following differences:

  • Additional options for these functions are available via the mallocctl() function and the MTMALLOC_OPTIONS environment variable, as described below.

  • A freed pointer that is passed to free() or realloc() will send a SIGABRT signal to the calling process, unless this behavior is disabled via the mallocctl() function or the MTMALLOC_OPTIONS environment variable.

  • Support for using adi(7) is not available.

The mallocctl() function controls the behavior of the mtmalloc library. The options fall into two general classes, debugging options and performance options.

MTDOUBLEFREE

Allows double free of a pointer. Setting value to 1 means yes and 0 means no. The default behavior of double free results in a core dump.

MTDEBUGPATTERN

Writes misaligned data into the buffer after free(). When the buffer is reallocated, the contents are verified to ensure that there was no access to the buffer after the free. If the buffer has been dirtied, a SIGABRT signal is delivered to the process. Setting value to 1 means yes and 0 means no. The default behavior is to not write misaligned data. The pattern used is 0xdeadbeef. Use of this option results in a performance penalty.

MTINITBUFFER

Writes misaligned data into the newly allocated buffer. This option is useful for detecting some accesses before initialization. Setting value to 1 means yes and 0 means no. The default behavior is to not write misaligned data to the newly allocated buffer. The pattern used is 0xbaddcafe. Use of this option results in a performance penalty.

MTCHUNKSIZE

This option changes the size of allocated memory when a pool has exhausted all available memory in the buffer. Increasing this value allocates more memory for the application. A substantial performance gain can occur because the library makes fewer calls to the OS for more memory. Acceptable number values are between 9 and 256. The default value is 9 for 32–bit code and 64 for 64–bit code. This value is multiplied by 8192.

MTEXCLUSIVE

This option is now a no-op as all threads have an exclusive set of caches.

MTREALFREE

This option sets the threshold for calling madvise(3C) with MADV_FREE. Calling madvise() will result in the memory associated with the allocation being returned to the kernel. When freed, allocations greater than value*pagesize will have madvise() called. If value is less than 2, it will be set to 2.

Environment Variables

MTMALLOC_OPTIONS

A comma separated list of options. The supported options are:

MTEXCLUSIVE=Y

This is a no-op. All threads have exclusive access to a set of caches.

MTMAXCACHE=16, 17, 18, 19, 20, or 21

By default, allocations less than 216 bytes are allocated from buckets indexed by thread ID. Using this MTMALLOC_OPTION setting, variable size of the cached allocations can be increased to 217, 218, 218, 219, 220, or 221 by setting MTMAXCACHE to 17, 18, 19, 20, or 21. If MTMAXCACHE is set to less than 16, it is reset to 16. If MTMAXCACHE is set to more than 21, then it is reset to 21. This all occurs silently.

MTCHUNKSIZE=xx

Allocation buckets are sized by the chunk size and the size of the allocation request. The default setting is 9 for 32-bit applications and 64 for 64 bit applications. For the cost of address space, performance can sometimes be enhanced by increasing this parameter. For more information, see the mallocctl(3MALLOC) man page.

MTREALFREE=xx

If xx > 1, set the threshold for calling madvise(3C) with MADV_FREE. Calling madvise() will result in the memory associated with the allocation being returned to the kernel. When freed, allocations greater than xx*pagesize will have madvise() called. If xx is less than 2, it will be set to 2.

MTDEBUGPATTERN=Y

Writes misaligned data into the buffer after free(). When the buffer is reallocated, the contents are verified to ensure that there was no access to the buffer after the free. If the buffer has been dirtied, a SIGABRT signal is delivered to the process. The default behavior is not to write misaligned data. The pattern used is 0xdeadbeef. Use of this option results in a performance penalty.

MTINITBUFFER=Y

Writes misaligned data into the newly allocated buffer. This option is useful for detecting some accesses before initialization. The default behavior is not to write misaligned data to the newly allocated buffer. The pattern used is 0xbaddcafe. Use of this option results in a performance penalty.

MTDOUBLEFREE=Y

Allows double free of a pointer. The default behavior of double free results in a core dump.

Usage

See malloc(3C) for an overview and comparison of all the allocation libraries provided by Oracle Solaris.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
MT-Level
Safe

See Also

brk(2), getrlimit(2), dlopen(3C), madvise(3C), malloc(3C), signal.h(3HEAD), libmtmalloc(3LIB), attributes(7)

Warnings

Undefined results will occur if the size requested for a block of memory exceeds the maximum size of a process's heap. This information may be obtained using the getrlimit() function.