Low level interface for scalable memory allocation.
extern "C" { // Scalable analogs of C memory allocator void* scalable_malloc( size_t size ); void scalable_free( void* ptr ); void* scalable_calloc( size_t nobj, size_t size ); void* scalable_realloc( void* ptr, size_t size ); // Analog of _msize/malloc_size/malloc_usable_size. size_t scalable_msize( void* ptr ); // Scalable analog of posix_memalign int scalable_posix_memalign( void** memptr, size_t alignment, size_t size ); // Aligned allocation void* scalable_aligned_malloc( size_t size, size_t alignment); void scalable_aligned_free( void* ptr ); void* scalable_aligned_realloc( void* ptr, size_t size, size_t alignment ); // Return values for scalable_allocation_* functions typedef enum { TBBMALLOC_OK, TBBMALLOC_INVALID_PARAM, TBBMALLOC_UNSUPPORTED, TBBMALLOC_NO_MEMORY, TBBMALLOC_NO_EFFECT } ScalableAllocationResult; typedef enum { // to turn on/off the use of huge memory pages TBBMALLOC_USE_HUGE_PAGES, // to set a threshold for the allocator memory usage; // exceeding it will forcefully clean internal memory buffers TBBMALLOC_SET_SOFT_HEAP_LIMIT } AllocationModeParam; // Set allocator-specific allocation modes. int scalable_allocation_mode(int param, intptr_t value); typedef enum { // Clean internal allocator buffers for all threads. TBBMALLOC_CLEAN_ALL_BUFFERS, // Clean internal allocator buffer for current thread only. TBBMALLOC_CLEAN_THREAD_BUFFERS } ScalableAllocationCmd; // Call allocator-specific commands. int scalable_allocation_command(int cmd, void *param); }
#include "tbb/scalable_allocator.h"
These functions provide a C level interface to the scalable allocator. With the exception of scalable_allocation_mode and scalable_allocation_command, each routine scalable_x behaves analogously to library function x. The routines form the two families shown in the table below, "C Interface to Scalable Allocator" . Storage allocated by a scalable_x function in one family must be freed or resized by a scalable_x function in the same family, not by a C standard library function. Likewise storage allocated by a C standard library function should not be freed or resized by a scalable_x function.
Family |
Allocation Routine |
Deallocation Routine |
Analogous Library |
---|---|---|---|
1 |
scalable_malloc |
scalable_free |
C standard library |
scalable_calloc |
|||
scalable_realloc |
|||
scalable_posix_memalign |
POSIX* |
||
2 |
scalable_aligned_malloc |
scalable_aligned_free |
Microsoft* C run-time library |
scalable_aligned_realloc |
Returns
The usable size of the memory block pointed to by ptr if it was allocated by the scalable allocator. Returns zero if ptr does not point to such a block.
Parameter | Description |
---|---|
TBBMALLOC_USE_HUGE_PAGES |
scalable_allocation_mode(TBBMALLOC_USE_HUGE_PAGES, 1) enables the use of huge pages by the allocator if supported for the operating system, scalable_allocation_mode(TBBMALLOC_USE_HUGE_PAGES, 0) disables it. Setting TBB_MALLOC_USE_HUGE_PAGES environment variable to 1 has the same effect as scalable_allocation_mode(TBBMALLOC_USE_HUGE_PAGES, 1). The mode set with scalable_allocation_mode() takes priority over the environment variable. May return: TBBMALLOC_NO_EFFECT if huge pages are not supported on the platform. |
TBBMALLOC_SET_SOFT_HEAP_LIMIT |
scalable_allocation_mode(TBBMALLOC_SET_SOFT_HEAP_LIMIT, size) sets a threshold of size bytes on the amount of memory the allocator takes from OS. Exceeding the threshold will urge the allocator to release memory from its internal buffers; however it does not prevent from requesting more memory if needed. |
Parameter | Description |
---|---|
TBBMALLOC_CLEAN_ALL_BUFFERS |
scalable_allocation_command(TBBMALLOC_CLEAN_ALL_BUFFERS, 0) cleans internal memory buffers of the allocator, and possibly reduces memory footprint. It may result in increased time for subsequent memory allocation requests. The command is not designed for frequent use, and careful evaluation of the performance impact is recommended. May return: TBBMALLOC_NO_EFFECT if no buffers were released. |
TBBMALLOC_CLEAN_THREAD_BUFFERS |
scalable_allocation_command(TBBMALLOC_CLEAN_THREAD_BUFFERS, 0) cleans internal memory buffers but only for the calling thread. It may result in increased time for subsequent memory allocation requests; careful evaluation of the performance impact is recommended. May return: TBBMALLOC_NO_EFFECT if no buffers were released. |