DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

(gmp.info.gz) Custom Allocation

Info Catalog (gmp.info.gz) BSD Compatible Functions (gmp.info.gz) Top (gmp.info.gz) Language Bindings
 
 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.
 
    This feature is available in the Berkeley compatibility library
 ( BSD Compatible Functions) as well as the main GMP library.
 
  - 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 ( 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 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.
 
    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);
 
Info Catalog (gmp.info.gz) BSD Compatible Functions (gmp.info.gz) Top (gmp.info.gz) Language Bindings
automatically generated byinfo2html