Next: , Previous: , Up: MPFR Interface   [Index]

5.16 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:

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. The mpfr_custom_init_set macro is not usable in contexts where an expression is expected, e.g., inside for(...) or before a comma operator.

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 the same sign as kind;
  • if abs(kind) = MPFR_ZERO_KIND, x is set to the zero of the same sign as kind;
  • if abs(kind) = MPFR_REGULAR_KIND, x is set to the regular number whose sign is the one of kind, and whose exponent and significand are given by exp and significand.

In all cases, significand will be used directly for further computing involving x. This function does 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 and the significand is considered in [1/2,1). But if x is NaN, infinity or zero, contrary to mpfr_get_exp (where the behavior is undefined), the return value is here an unspecified, valid value of the mpfr_exp_t type. 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.

Next: Internals, Previous: Compatibility With MPF, Up: MPFR Interface   [Index]