The decNumber Library, version 3.36
Copyright (c) IBM Corporation, 2006. All rights reserved. ©
| 6 Jul 2006 |
[previous | contents | next]
|
This section describes some additional features of the decNumber
package, intended to be used when extending the package or tuning its
performance. If you are just using the package for applications, using
full IEEE arithmetic, you should not need to modify the parameters
controlling these features.
The decNumber package incorporates a number of compile-time parameters.
If any of these parameters is changed, all the decNumber source files
being used must be recompiled to ensure correct operation.
Two parameters are used to tune the trade-offs between storage
use and speed. The first of these determines the granularity of
calculations (the number of digits per unit of storage) and is normally
set to three or to a power of two. The second is normally set so
that short numbers (tens of digits) require no storage
management – working buffers for operations will be stack based,
not dynamically allocated.
These are:
- DECDPUN
- This parameter is set in the decNumber.h file, and must be an
integer in the range 1 through 9. It sets the number of digits held in
one unit, which in turn alters the
performance and other characteristics of the library.
In particular:
-
If DECDPUN is 1, conversions are fast, but arithmetic
operations are at their slowest. In general, as the value
of DECDPUN increases, arithmetic speed improves and conversion
speed gets worse.
-
Conversions between the decNumber internal format and the decimal64
and other compressed formats are fastest – sometimes by as much
as a factor of 4 or 5 – when DECDPUN is 3 (because
Densely Packed Decimal encodes digits in groups of three).
-
If DECDPUN is not 1, 3, or a power of two, calculations
converting digits to units and vice versa are slow; this may slow
some operations by up to 20%.
-
If DECDPUN is greater than 4, either non-ANSI-89 C integers or
library calls have to be used for 64-bit intermediate calculations.[1]
The suggested value for DECDPUN is 3, which gives good
performance for working with the compressed decimal formats. If the
compressed formats are not being used, or 64-bit integers are
unavailable (see DECUSE64, below), then measuring the effect of
changing DECDPUN to 4 is suggested.
If the library is to be used for high precision calculations (many tens
of digits) then it is recommended that measurements be made to
evaluate whether to set DECDPUN to 8 (or possibly to 9, though
this will often be slower).
- DECBUFFER
- This parameter is set in the decNumberLocal.h file, and must
be a non-negative integer. It sets the precision, in digits, which the
operator functions will handle without allocating dynamic storage.[2]
One or more DECBUFFER-sized buffers will be allocated on the
stack, depending on the function; comparison, additions, subtractions,
and exponentiation all allocate one, multiplication allocates two, and
division allocates three; more complex operations may allocate more.
It is recommended that DECBUFFER be a multiple of DECDPUN
and also a multiple of 4, and large enough to hold common numbers in
your application.
A third compile-time parameter controls the layout of the
compressed decimal formats. The
storage of a number in these formats may be chosen to either follow
the byte ordering (‘endianness’) of the computing platform or to
use fixed ordering.
For best performance when using these formats, this parameter
should be set to 1.
The parameter is set in the decNumberLocal.h file, and is:
- DECENDIAN
- This must be either 1 or 0. If 1, which is recommended, the
formats will be stored following the endianness of the underlying
computing platform.
For example, for AMD and Intel x86 architecture machines, which are
little-endian, the byte containing the sign bit of the format
is at the highest memory address; for IBM z-Series machines, which
are big-endian, the byte containing the sign bit of the
format is at the lowest memory address. This setting means that the
decimal formats will be stored using the same ordering as binary
integer and floating-point formats on the same machine, and also
allows much faster conversions (up to a factor of three) to and from
the decNumber internal form.
Setting DECENDIAN to 0 forces the formats to be stored using
fixed, big-endian, ordering. This is provided for compatibility with
earlier versions of the decNumber package.
A fourth compile-time parameter allows the use of 64-bit integers to
improve the performance of certain operations (notably multiplication
and the mathematical functions), even when DECDPUN is less
than 5. (64-bit integers are required when DECDPUN is 5 or
more.)
The parameter is set in the decNumberLocal.h file, and is:
- DECUSE64
- This must be either 1 or 0. If 1, which is recommended, 64-bit
integers will be used for most multiplications and mathematical
functions when DECDPUN<=4, and for most operations
when DECDPUN>4. If set to 0, 64-bit integer support is not
used when DECDPUN<=4, and the maximum value for DECDPUN
is then 4.
Three further compile-time parameters control the inclusion of extra
code which provides for full checking of input arguments, run-time
internal tracing control, and storage allocation auditing. These
options are usually disabled, for best performance, but are useful for
testing and when introducing new conversion routines,
etc.
These parameters are all set in the decNumberLocal.h file, and
are:
- DECCHECK
- This must be either 1 or 0. If 1, code which checks input
structure references will be included in the module. This checks that
the structure references are not NULL, and that they refer to
valid (internally consistent in the current context) structures. If an
invalid reference is detected,
the DEC_Invalid_operation status bit is set
(which may cause a trap), and any result will be a valid number of
undefined value.
This option is useful for verifying programs which construct decNumber
structures explicitly.
Some operations take more than twice as long with this checking enabled,
so it is normally assumed that all decNumbers are valid and DECCHECK
is set to 0.
- DECALLOC
- This must be either 1 or 0. If 1, all dynamic storage usage is
audited and extra space is allocated to enable buffer overflow
corruption checks. The cost of these checks is fairly small, but the
setting should normally be left as 0 unless changes are being made to
the decNumber.c source file.
- DECTRACE
- This must be either 1 or 0. If 1, certain critical values are
traced (using printf) as operations take place. This is intended
for development use only, so again should normally be left as 0.
A final compile-time parameter enables the inclusion of extra
code which implements and enforces the subset arithmetic defined by
ANSI X3.274. This option should be disabled, for best performance,
unless the subset arithmetic is required.
The parameter is set in the decContext.h file, and
is:
- DECSUBSET
- This must be either 1 or 0. If 1, subset arithmetic is enabled.
This setting includes the extended flag in the decContext
structure and all code which depends on that flag.
Setting DECSUBSET to 0 improves the performance of many
operations by 10%–20%.
Footnotes:
[1] |
The decNumber library currently assumes that non-ANSI-89 64-bit
integers are available if DECDPUN is greater than 4.
See also the DECUSE64 tuning parameter.
|
[2] |
Dynamic storage may still be allocated in certain cases, but in
general this is rare.
|
[previous | contents | next]