Next: Language Bindings, Previous: .Net Interface, Up: MPIR [Index]
By default MPIR uses malloc
, realloc
and free
for memory
allocation, and if they fail MPIR 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.
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 MPIR, apart from
temporary space from alloca
if that function is available and MPIR is
configured to use it (see Build Options).
Be sure to call mp_set_memory_functions
only when there are no
active MPIR objects allocated using the previous memory functions! Usually
that means calling it before any other MPIR function.
The functions supplied should fit the following declarations:
Return a pointer to newly allocated space with at least alloc_size bytes.
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.
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 old_size parameters to reallocate_function and
free_function are passed for convenience, but of course can be ignored
if not needed. 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.
MPIR may use allocated blocks to hold pointers to other allocated blocks. This will limit the assumptions a conservative garbage collection scheme can make.
Any custom allocation functions must align pointers to limb boundaries. Thus if a limb is eight bytes (e.g. on x86_64), then all blocks must be aligned to eight byte boundaries. Check the configuration options for the custom allocation library in use. It is not necessary to align blocks to SSE boundaries even when SSE code is used. All MPIR assembly routines assume limb boundary alignment only (which is the default for most standard memory managers).
Since the default MPIR 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 MPIR sources if
this is a problem.
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);
Next: Language Bindings, Previous: .Net Interface, Up: MPIR [Index]