GMP symbol naming (and the history thereof)?

[Torbjorn Granlund]

About gmp-func-list.txt.  Note that this file was laid out for easy
automated processing for the shared library overhead reduction project.

nisse at lysator.liu.se (Niels Möller) writes:

  Here are some comments on a few that stood out.
  
Thanks!

  > __gmpn_add_n_sub_n                              
  > __gmpn_add_nc                                   
  
  I think these make sense as public (we'd need to investigate how one
  best does both _n and _nc in C, with duplication or a tail call).
  
I didn't list __gmpn_add_n_sub_n as public since I consider it
experimental.  It seemed like a good idea, but I never managed to make
it faster, not even for the large operands for which is was intended.

The latter part is important, and the C implementation indeed just calls
add_n and sub_n piecewise.

All-in-all this is a highly specialised functon.

While __gmpn_add_nc makes more sense as public, I didn't suggest it to
be that for more practical reasons.  Many asm implementations do not
provide this entry point.

I am not against making it public, but it cannot be done without
additional work.

  > __gmpn_addcnd_n
  
  And this. (I think I'd prefer
  
    mp_limb_t
    mpn_cnd_add_n (mp_limb_t cnd, mp_ptr rp, mp_srcptr ap, mp_srcptr bp, mp_size_t n)
  
  but that's a minor detail, and view the cnd_-prefix as a family of
  functions. Some other potential members are mpn_cnd_copy, mpn_cnd_neg
  and mpn_cnd_swap, see
  http://git.lysator.liu.se/nettle/nettle/blobs/ecc-support/sec-modinv.c
  for one application).
  
I agree that would be a good naming cleanup.  Will you do the honours?

  > __gmpn_addlsh1_n                                
  > __gmpn_addlsh2_n                                
  > __gmpn_addlsh_n                                 
  
  Some of these would make sense as public (with some kind of fallback to
  addmul_1 if no more efficient loop is implemented).
  
Similar situation as with __gmpn_add_nc; this requires work before they
can be made public.  We want to keep HAVE_NATIVE_ properly set for
internal use, someting to keep in mind if we work on making these
public.

  > __gmpn_divisible_p                              
  
  Would make sense as public, I think.
  
Sure.

  > __gmpn_gcdext_lehmer_n                          
  
  I think this would make sense as public, under a different name, e.g.,
  mpn_gcdext_n_basecase.
  
Maybe.  We need to worry about the itch/scratch interface.  For user
interface code, it seems to make sense to have scratch parameter less
functions.  Like __gmpn_divisible_p.

Should a mpn_gcd_n_basecase also be available, for symmetry?

  BTW, the other day I realized I'd like to extend the gcdext functions to
  allow gp == NULL, so callers who use them for modular inversion don't
  need to allocate space for a potentially large gcd. In this case, the
  functions should return 1 and produce the cofactor only if the gcd is 1,
  and otherwise return 0 to indicate failure.
  
I am always keen when the work falls on you.  :-)

Does the gcdext functions need a large gp area also when the caller
knows the gcd = 1?  (It might be deen as a somewhat dangerous user
interface to say "allocate enought space for the gcd".)

  > __gmpn_hgcd                                     
  > __gmpn_hgcd2                                    
  
  Some hgcd function should be public, possibly with interface tweaks.
  
Sure.  The Pari project asked for that, IIRC.

  > __gmpn_invert                           doc     
  
You're looking at an obsolete version of the list.

  The doc flag is a false positive. But it would make sense to have public
  invert and invertappr. (Or "reciprocal", if that's better).
  
Sure.  Again we have a scratch interface concern.

  > __gmpn_mulmod_bnm1                      doc
  
  Another false positive. But since this function has turned out to be so
  useful, it would make sense to make it public in some form.
  
Obsolete list again.

  > __gmpn_powlo                                    
  > __gmpn_powm                                     
  > __gmpn_powm_sec                                 
  > __gmpn_powm_sec_itch
  
  Should be public, possibly with interface tweaks.
  
I agree.  (Less sure about powlo, at least if we don't also make mullo
public...)

  > __gmpn_redc_1                                   
  > __gmpn_redc_2                                   
  > __gmpn_redc_n
  
  Should be public in some form, but since the bdiv interface redesign is
  not yet integrated, redc interfaces should change a bit too for
  consistency.
  
It seem likely that mpn_redc* will be supplanted by mpn_*bdiv*, right?

  > __gmpn_sqr_basecase                             
  
  This (and also mul_basecase) should be public. They're useful for crypto
  applications where numbers are known to be of moderate size and where
  low code complexity is desired.
  
I agree.  Should we consider a name change?  What about publishing
mullo_basecase?

We have 'sb', 'bc' and 'basecase' monikers for this general meaning.

There is a drawback with making these public, that sqr_basecase should
not be used below SQR_BASECASE_THRESHOLD.  Same for mullo_basecase vs
MULLO_BASECASE_THRESHOLD.  We could export variables such as
gmp_sqr_basecase_threshold, perhaps.  Again, work required.

Another more serious drawback: sqr_basecase does not currently work for
sizes over SQR_TOOM2_THRESHOLD.  Over that, some implementations,
including the C one, smash the stack.  For your proposed application,
crypto, stack smashing tend to trigger paranoic reactions.  :-)

(The mpn naming is messy.  That's not terrible internally, but we
shouldn't mess up peoples' minds with such public functions...)

  > __gmpn_zero                             doc decl
  
  Missing in the list is mpn_zero_p. Should be public.

You propose to move it from gmp-impl.h to gmp-h.in?  I'm fine with that.
(I didn't include any static functions, since they don't matter for the
shared lib overhead reductoon project.)

I am making some changes to the file suggesting some more public
functions, also adding "namechange?", "interface?", and "interface!".

-- 
Torbjörn