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 one to use MPFR in two ways:

• Either directly store a floating-point number as a mpfr_t on the stack.
• Either store its own representation on the stack and construct a new temporary mpfr_t each time it is needed.

Nothing has to be done to destroy the floating-point numbers except garbaging the used memory: all the memory management (allocating, destroying, garbaging) is left 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 floating-point numbers using mpfr_init and similar functions. 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.

Function: size_t mpfr_custom_get_size (mpfr_prec_t prec)

Return the needed size in bytes to store the significand of a floating-point number of precision prec.

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

Initialize a significand of precision prec, where 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 (GMP type, see Internals).

Function: void mpfr_custom_init_set (mpfr_t x, int kind, mpfr_exp_t exp, mpfr_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 floating-point number initialized with this function cannot be resized using mpfr_set_prec or mpfr_prec_round, or cleared using mpfr_clear! The 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 created 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_significand (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: mpfr_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 does not 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 of x 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.