On 2016-04-07 10:58:13 +0200, Torbjörn Granlund wrote: > I agree this should be made explicit; users should not need to worry > about the inner workings of our types (such as the fact that they > contain a pointer). > > Would you want to contribute a patch for our manual?
I propose the attached patch. I think that 3.4 Variable Conventions is the best section for such information. So, I've moved a part of the paragraph in 3.5 Parameter Conventions to a new paragraph in 3.4 with more information, and I've shortened the paragraph in 3.5 to make it deal with only parameter conventions. -- Vincent Lefèvre <vinc...@vinc17.net> - Web: <https://www.vinc17.net/> 100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/> Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)
diff -r 8ccd8e7de27b doc/gmp.texi --- a/doc/gmp.texi Sun Apr 03 16:50:36 2016 +0200 +++ b/doc/gmp.texi Thu Apr 07 13:07:28 2016 +0200 @@ -2070,6 +2070,18 @@ @} @end example +Such GMP types like @code{mpz_t} are implemented as one-element arrays +of certain structures. Declaring a variable creates an object with the +fields GMP needs, but variables are normally manipulated by using the +pointer to the object. For both behavior and efficiency reasons, it is +discouraged to make copies of the GMP object itself (either directly or +via aggregate objects containing such GMP objects). If copies are done, +all of them must be used read-only; using a copy as the output of some +function will invalidate all the other copies. Note that the actual +fields in each @code{mpz_t} etc are for internal use only and should not +be accessed directly by code that expects to be compatible with future +GMP releases. + @node Parameter Conventions, Memory Management, Variable Conventions, GMP Basics @section Parameter Conventions @@ -2118,12 +2130,9 @@ sometimes it's tricky to make that work, and an application might not want to bother supporting that sort of thing. -For interest, the GMP types @code{mpz_t} etc are implemented as one-element -arrays of certain structures. This is why declaring a variable creates an -object with the fields GMP needs, but then using it as a parameter passes a -pointer to the object. Note that the actual fields in each @code{mpz_t} etc -are for internal use only and should not be accessed directly by code that -expects to be compatible with future GMP releases. +Since GMP types are implemented as one-element arrays, using a GMP +variable as a parameter passes a pointer to the object. Hence the +call-by-reference. @need 1000
_______________________________________________ gmp-bugs mailing list gmp-bugs@gmplib.org https://gmplib.org/mailman/listinfo/gmp-bugs