Jim, thanks for taking a look at this.

Jim Jewett <report@bugs.python.org> wrote:
> (1)  I think this module would benefit greatly from a map explaining
>      what each file does, and perhaps from some reorganization. 

Just MAP.txt in the top level directory? Amaury suggested moving
the library into a subdirectory. I'm not sure about that. The
library would be out of sight, but is that a good thing?

> As best I can yet tell, there are about ~130 files, over a dozen directories,
> but the only ones that directly affect the implementation are a subset (~33)
> of the *.c and *h files in Modules/_decimal/ (and not subdirectories).  

Indeed the top level directory contains _decimal.c and all files
from libmpdec. Almost all files are required.

The three subdirectories contain:

  tests/       ->  library tests
  python/      ->  extended module tests
  literature/  ->  pointers to papers and explanations for trickier algorithms.

> Even files that do affect the implementation, such as mpdecimal.c,
> also seem to have functions thrown in just for testing small pieces
> of functionality, such as Newton Division.

That is correct. They were deliberately added in that place because they rely
on a couple of inline functions and I have a policy of testing the exact code
that the original function relies on.

The alternative is to extract all functions needed, move them to the test
directory and hope that the code doesn't get stale. But if you have a better
idea, I'd be glad to hear it: I don't like the test functions in that place
either.

The reason that Newton Division is tested for ridiculously small precisions
like prec=1 is that it should pass IBM's test suite just like the regular
division function. (Also, small precisions are most likely to expose problems).

> There may also be some code that really isn't needed, except possibly for
> backwards compatibility, and could be #ifdef'ed or at least commented.

I'm not aware of any except for whole files:

  mpsignal.c  ->  signaling wrappers for the mpdecimal.c functions,
                  not needed for _decimal.c but part of libmpdec.

  mptest.h    ->  header for running the tests.

  bench.c     ->  library benchmark.

> Turkish un/dotted-i problem when lowercasing -- but why is a decimal
> library even worried about casing?

"Infinity", "InFinItY", "iNF" are all allowed by the specification.

> (2)  Is assembly allowed?

I was under the assumption that it is allowed:

Python/pymath.c:23:    __asm__ __volatile__ ("fnstcw %0" : "=m" (cw));
Python/pymath.c:28:    __asm__ __volatile__ ("fldcw %0" : : "m" (cw));
Python/ceval.c:43:    asm volatile ("mftbu %0" : "=r" (tbu) );
Python/ceval.c:44:    asm volatile ("mftb  %0" : "=r" (tb)  );
Python/ceval.c:45:    asm volatile ("mftbu %0" : "=r" (tbu2));
Python/ceval.c:59:     __asm__ __volatile__("rdtsc" : "=A" (val))
Python/ceval.c:69:    __asm__ __volatile__("rdtsc" : \

> If not, please make it clear that vcdiv64.asm is just an optional speedup,
> and that the code doesn't rely upon it.

No code relies on asm. Assembly is only used for the double word mul/divmod
primitives in typearith.h and the Pentium PRO modular multiplication in
umodarith.h, and there are ANSI versions for everything.

The library really compiles with any compiler I have tested, including
compilers without uint64_t like CompCert (CompCert does not compile
Python for example, but for other reasons).

> (3) Are there parts of this library that provide functionality NOT
>     in the current decimal library?  If so, this should be at least
>     documented, and perhaps either removed or exposed.

Apart from mpsignal.c (see above), there are probably a couple of things
in the header files like mpd_invroot(). _mpd_qinvroot() from mpdecimal.c
*is* needed because the square root is calculated in terms of the
inverse square root.

Are these (probably) minor instances of additional functionality a
big problem for you? Because for me it would be a hassle to maintain
diverging versions of libmpdec and the Python version of libmpdec.

This is also related to testing: The complete test suite (all tests
against decNumber and decimal.py) under Valgrind takes 8 months to
run.

My question is: Where should I document these things and in what detail?