13 Custom Allocation

By default GMP uses malloc, realloc and free for memory allocation, and if they fail GMP prints a message to the standard error output and terminates the program.

Alternate functions can be specified, to allocate memory in a different way or to have a different error action on running out of memory.

Function: void mp_set_memory_functions (
void *(*alloc_func_ptr) (size_t),
void *(*realloc_func_ptr) (void *, size_t, size_t),
void (*free_func_ptr) (void *, size_t))

Replace the current allocation functions from the arguments. If an argument is NULL, the corresponding default function is used.

These functions will be used for all memory allocation done by GMP, apart from temporary space from alloca if that function is available and GMP is configured to use it (see Build Options).

Be sure to call mp_set_memory_functions only when there are no active GMP objects allocated using the previous memory functions! Usually that means calling it before any other GMP function.

The functions supplied should fit the following declarations:

Function: void * allocate_function (size_t alloc_size)

Return a pointer to newly allocated space with at least alloc_size bytes.

Function: void * reallocate_function (void *ptr, size_t old_size, size_t new_size)

Resize a previously allocated block ptr of old_size bytes to be new_size bytes.

The block may be moved if necessary or if desired, and in that case the smaller of old_size and new_size bytes must be copied to the new location. The return value is a pointer to the resized block, that being the new location if moved or just ptr if not.

ptr is never NULL, it’s always a previously allocated block. new_size may be bigger or smaller than old_size.

Function: void free_function (void *ptr, size_t size)

De-allocate the space pointed to by ptr.

ptr is never NULL, it’s always a previously allocated block of size bytes.

A byte here means the unit used by the sizeof operator.

The reallocate_function parameter old_size and the free_function parameter size are passed for convenience, but of course they can be ignored if not needed by an implementation. The default functions using malloc and friends for instance don’t use them.

No error return is allowed from any of these functions, if they return then they must have performed the specified operation. In particular note that allocate_function or reallocate_function mustn’t return NULL.

Getting a different fatal error action is a good use for custom allocation functions, for example giving a graphical dialog rather than the default print to stderr. How much is possible when genuinely out of memory is another question though.

There’s currently no defined way for the allocation functions to recover from an error such as out of memory, they must terminate program execution. A longjmp or throwing a C++ exception will have undefined results. This may change in the future.

GMP may use allocated blocks to hold pointers to other allocated blocks. This will limit the assumptions a conservative garbage collection scheme can make.

Since the default GMP allocation uses malloc and friends, those functions will be linked in even if the first thing a program does is an mp_set_memory_functions. It’s necessary to change the GMP sources if this is a problem.

Function: void mp_get_memory_functions (
void *(**alloc_func_ptr) (size_t),
void *(**realloc_func_ptr) (void *, size_t, size_t),
void (**free_func_ptr) (void *, size_t))

Get the current allocation functions, storing function pointers to the locations given by the arguments. If an argument is NULL, that function pointer is not stored.

For example, to get just the current free function,

void (*freefunc) (void *, size_t);

mp_get_memory_functions (NULL, NULL, &freefunc);