_ptr and _srcptr types

[Niels Möller]

Emmanuel Thomé <Emmanuel.Thome at inria.fr> writes:

> diff -r aab8a010d10f -r 14b2416f45de doc/gmp.texi
> --- a/doc/gmp.texi	Mon May 21 00:13:27 2018 +0200
> +++ b/doc/gmp.texi	Thu May 24 00:31:28 2018 +0200
> @@ -1982,6 +1982,42 @@
>  Also, in general @code{mp_bitcnt_t} is used for bit counts and ranges, and
>  @code{size_t} is used for byte or character counts.
>  
> + at sp 1
> +
> + at cindex Pointer types
> + at tindex @code{mpz_ptr}
> + at tindex @code{mpz_srcptr}
> + at tindex @code{mpq_ptr}
> + at tindex @code{mpq_srcptr}
> + at tindex @code{mpf_ptr}
> + at tindex @code{mpf_srcptr}
> + at tindex @code{gmp_randstate_ptr}
> + at tindex @code{gmp_randstate_srcptr}
> +Internally, GMP data types such as @code{mpz_t} are defined as
> +one-element arrays, whose element type is part of the GMP
> +internals (@pxref{Internals}). In some cases, it may be desirable to manipulate
> +pointers to this element type. Types such as @code{mpz_ptr} and
> + at code{mpz_srcptr} are defined for this purpose. 

I think I'd like to add something like

  When an array is used as a function argument in C, it is not passed by
  value, instead its value is a pointer to the first element. In C
  jargon, this is sometimes referred to as the array "decaying" to a
  pointer. For GMP types like mpz_t, that means that the function called
  gets a pointer to the caller's mpz_t value, which is why no explicit &
  operator is needed when passing output arguments. [this is related to
  the section Parameter Conventions]
  
  GMP defines names for these pointer types, e.g., mpz_ptr corresponding
  to mpz_t, and mpz_srcptr corresponding to const mpz_t. Most functions
  don't need to use these pointer types directly; it works fine to
  declare a function using the mpz_t or const mpz_t as the argument
  types, the same "pointer decay" happens in the background regardless.

  Occasionally, it is useful to manipulate pointers directly, e.g, to
  conditionally swap *references* to a function's inputs without
  changing the *values* as seen by the caller, or returning a pointer to
  an mpz_t which is part of a larger structure. For these cases, the
  pointer types are necessary. And a mpz_ptr can be passed as argument
  to any GMP function declared to take an mpz_t argument.

> +equivalent to the following code, which is given for illustratory
> +purposes only:
> +
> + at example
> +    typedef some_internal_data_type mpz_t[1];
> +    typedef some_internal_data_type * mpz_ptr;
> +    typedef const some_internal_data_type * mpz_srcptr;
> + at end example

I think it's confusing with a made-up name for the internal types, but
actual names for types defined. I'd prefer to either use the actual
internal name __mpz_struct instead of some_internal_data_type above, or
change to the obviously made up name foo consistently, like

    typedef foo_internal foo_t[1];
    typedef foo_internal * foo_ptr;
    typedef const foo_internal * foo_srcptr;

Regards,
/Niels

-- 
Niels Möller. PGP-encrypted email is preferred. Keyid 368C6677.
Internet email is subject to wholesale government surveillance.