Next: , Previous: Compatibility with MPF, Up: MPFR Interface


5.15 Custom Interface

Some applications use a stack to handle the memory and their objects. However, the MPFR memory design is not well suited for such a thing. So that such applications are able to use MPFR, an auxiliary memory interface has been created: the Custom Interface.

The following interface allows them to use MPFR in two ways:

Nothing has to be done to destroy the FP numbers except garbaging the used memory: all the memory stuff (allocating, destroying, garbaging) is kept to the application.

Each function is this interface is also implemented as a macro for efficiency reasons.

Note 1: MPFR functions may still initialize temporary FP numbers using standard mpfr_init. See Custom Allocation (GNU MP).

Note 2: MPFR functions may use the cached functions (mpfr_const_pi for example), even if they are not explicitly called. You have to call mpfr_free_cache each time you garbage the memory iff mpfr_init, through GMP Custom Allocation, allocates its memory on the application stack.

Note 3: This interface is preliminary.

— Function: size_t mpfr_custom_get_size (mp_prec_t prec)

Return the needed size in bytes to store the mantissa of a FP number of precision prec.

— Function: void mpfr_custom_init (void *mantissa, mp_prec_t prec)

Initialize a mantissa of precision prec. mantissa must be an area of mpfr_custom_get_size (prec) bytes at least and be suitably aligned for an array of mp_limb_t.

— Function: void mpfr_custom_init_set (mpfr_t x, int kind, mp_exp_t exp, mp_prec_t prec, void *mantissa)

Perform a dummy initialization of a mpfr_t and set it to:

In all cases, it uses mantissa directly for further computing involving x. It will not allocate anything. A FP number initialized with this function cannot be resized using mpfr_set_prec, or cleared using mpfr_clear! mantissa must have been initialized with mpfr_custom_init using the same precision prec.

— Function: int mpfr_custom_get_kind (mpfr_t x)

Return the current kind of a mpfr_t as used by mpfr_custom_init_set. The behavior of this function for any mpfr_t not initialized with mpfr_custom_init_set is undefined.

— Function: void *mpfr_custom_get_mantissa (mpfr_t x)

Return a pointer to the mantissa used by a mpfr_t initialized with mpfr_custom_init_set. The behavior of this function for any mpfr_t not initialized with mpfr_custom_init_set is undefined.

— Function: mp_exp_t mpfr_custom_get_exp (mpfr_t x)

Return the exponent of x, assuming that x is a non-zero ordinary number. The return value for NaN, Infinity or Zero is unspecified but doesn't produced any trap. The behavior of this function for any mpfr_t not initialized with mpfr_custom_init_set is undefined.

— Function: void mpfr_custom_move (mpfr_t x, void *new_position)

Inform MPFR that the mantissa has moved due to a garbage collect and update its new position to new_position. However the application has to move the mantissa and the mpfr_t itself. The behavior of this function for any mpfr_t not initialized with mpfr_custom_init_set is undefined.

See the test suite for examples.