17694, "lydia-duncan", "[Library Stabilization] What should we do about "no doc" bigint.mpz and mpzStruct()?", "2021-05-12T20:08:13Z"
We currently document the mpz field in the bigint type and define a method bigint.mpzStruct() which returns an instance of __mpz_struct (which comes from the GMP module). Both of these are implementation details potentially unsuited for what is intended to be more of a Chapel type than a type that is tied to GMP. However, this information could be useful to users.
We could potentially "no doc" both of these symbols. We could also choose to move mpzStruct() to the GMP module, ensuring that it relies on the BigInteger module.
Brad says:
I feel like maybe we should just leave them where they are and mark them as being part of an "expert / could potentially change" interface / maybe add a --warn-unstable warning for them. Specifically, I think thatâas part of our multiresolution strategyâthere ought to be some way of dropping into the guts of the GMP type to get at the underlying data (similar to how one might want to poke into the guts of the array implementation and get the C pointer to the buffer(s) implementing their array). So I'd be inclined not to no doc it.
Another approach would be to rename mpzStruct() to something like getImplDetails() or getGuts() and note that the behavior depends on the implementation of bigint (noting that, in our current GMP-based implementation, it will return an mpz structure). That would make it less GMP-specific without taking away the ability to get at the field.
If we do not "no doc" both of these symbols or move mpzStruct(), we should make the use of GMP public since they are provided by its interface.