8.2 Nails

Everything in this section is highly experimental and may disappear or be subject to incompatible changes in a future version of GMP.

Nails are an experimental feature whereby a few bits are left unused at the top of each mp_limb_t. This can significantly improve carry handling on some processors.

All the mpn functions accepting limb data will expect the nail bits to be zero on entry, and will return data with the nails similarly all zero. This applies both to limb vectors and to single limb arguments.

Nails can be enabled by configuring with ‘--enable-nails’. By default the number of bits will be chosen according to what suits the host processor, but a particular number can be selected with ‘--enable-nails=N’.

At the mpn level, a nail build is neither source nor binary compatible with a non-nail build, strictly speaking. But programs acting on limbs only through the mpn functions are likely to work equally well with either build, and judicious use of the definitions below should make any program compatible with either build, at the source level.

For the higher level routines, meaning mpz etc, a nail build should be fully source and binary compatible with a non-nail build.

Macro: GMP_NAIL_BITS

Macro: GMP_NUMB_BITS

Macro: GMP_LIMB_BITS

GMP_NAIL_BITS is the number of nail bits, or 0 when nails are not in use. GMP_NUMB_BITS is the number of data bits in a limb. GMP_LIMB_BITS is the total number of bits in an mp_limb_t. In all cases

GMP_LIMB_BITS == GMP_NAIL_BITS + GMP_NUMB_BITS

Macro: GMP_NAIL_MASK

Macro: GMP_NUMB_MASK

Bit masks for the nail and number parts of a limb. GMP_NAIL_MASK is 0 when nails are not in use.

GMP_NAIL_MASK is not often needed, since the nail part can be obtained with x >> GMP_NUMB_BITS, and that means one less large constant, which can help various RISC chips.

Macro: GMP_NUMB_MAX

The maximum value that can be stored in the number part of a limb. This is the same as GMP_NUMB_MASK, but can be used for clarity when doing comparisons rather than bit-wise operations.

The term “nails” comes from finger or toe nails, which are at the ends of a limb (arm or leg). “numb” is short for number, but is also how the developers felt after trying for a long time to come up with sensible names for these things.

In the future (the distant future most likely) a non-zero nail might be permitted, giving non-unique representations for numbers in a limb vector. This would help vector processors since carries would only ever need to propagate one or two limbs.

This document was generated on March 31, 2014 using texi2html 5.0.