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:

• Either they directly store the MPFR FP number as a mpfr_t on the stack.
• Either they store their own representation of a FP number on the stack and construct a new temporary mpfr_t each time it is needed.

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 in this interface is also implemented as a macro for efficiency reasons: for example mpfr_custom_init (s, p) uses the macro, while (mpfr_custom_init) (s, p) uses the function.

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 significand of a FP number of precision prec.

Function: void mpfr_custom_init (void *significand, mp_prec_t prec)

Initialize a significand of precision prec. significand 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 *significand)

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

• if ABS(kind) == MPFR_NAN_KIND, x is set to NaN;
• if ABS(kind) == MPFR_INF_KIND, x is set to the infinity of sign sign(kind);
• if ABS(kind) == MPFR_ZERO_KIND, x is set to the zero of sign sign(kind);
• if ABS(kind) == MPFR_REGULAR_KIND, x is set to a regular number: x = sign(kind)*significand*2^exp

In all cases, it uses significand 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! significand 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 significand 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 produce 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 significand has moved due to a garbage collect and update its new position to new_position. However the application has to move the significand 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.