Re: [gfortran] Add malloc and free intrinsics

[Brooks Moses <bmoses at stanford dot edu>]

François-Xavier Coudert wrote:
> I would really welcome comments on the doc part, since I am not a
> native english speaker, and I was not too confident with what should
> be said. Thanks in advance.

In my opinion, your english in the examples is perfectly fine.  :)  I do 
have a couple of minor quibbles, but no more than I'd expect for a 
native speaker -- though I'll write rather more about why I have 
problems with them.

>  * @code{EXPONENT}:      EXPONENT,  Exponent function
> +* @code{FREE}:          FREE,      Memory freeing subroutine
>  * @code{FLOOR}:         FLOOR,     Integer floor function

The phrase "memory freeing subroutine" sounds a bit informal for this; 
in part because it contains an active verb where nothing else in the 
list does.  I'd suggest "Subroutine to free memory", but that doesn't 
fit the pattern of having "function" or "subroutine" at the end.

Thus: "Memory de-allocation subroutine", maybe.

> +@item @emph{Arguments}:
> +@multitable @columnfractions .15 .80
> +@item @var{PTR} @tab The type shall be @code{INTEGER} with intent in.
> +@end multitable

If it were just me writing this, I would put the "in" in quotes, there, 
under the grammatical rule of putting quotes around words when one is 
talking about them as words rather than about their meaning.  But it's 
rather ambiguous whether that applies, so what I would really do here is 
confirm that this is how it's written in the rest of the documentation. 
 (You've probably already checked that, though.)

Actually, is this how the documentation phrases this in general?  It 
seems a bit odd to be talking about "intent in" with respect to an 
actual argument on the calling side, rather than a dummy argument in the 
called function.

> +@item @emph{Return value}:
> +The return value is of type @code{INTEGER(K)}, with @var{K} such that
> +@code{INTEGER(K)} has the same size as C pointers (@code{sizeof(void *)}).

Pedantically, @code{INTEGER(K)} doesn't have a size.  I would instead 
write "...such that variables of type @code{INTEGER(K)} have the same 
size as C pointers...."

I'd also write it as "...with @var{K} defined such that...," but others 
might complain that that's wordier than it needs to be.


Also, I have some technical issues with the example:

> +@item @emph{Example}:
> +@smallexample
> +program test_malloc
> +  integer i
> +  integer ptr_x
> +  real*8 x(*)
> +  pointer(ptr_x,x)

This is a Cray-pointer version of the pointer statement, not the 
standard Fortran version, yes?  If so, I think that this should be 
pointed out clearly -- either by noting in the documentation that MALLOC 
is primarily used for Cray pointers, or by explicitly stating somewhere 
that the example illustrates their use with Cray pointers, or both.

I'm also not happy about putting an example into the documentation that 
isn't compilable with current releases of the code.  At the least, I 
think that there should be a statement in the example that says "THIS 
EXAMPLE IS NOT CURRENTLY FUNCTIONAL" that we take out once the Cray 
pointer patch is officially approved.

> +
> +  ptr_x = malloc(20*8)
> +  do i = 1, n

Either that n should be 20, or the 20 should be n and the n declared and 
initialized.

> +    x(i) = sqrt(1.0d0 / i)
> +  end do
> +  call free(ptr_x)
> +end program test_malloc
> +@end smallexample

I think it might be nice to write out the x(i) values, so that the 
program isn't effectively a no-op.  But, again, that's something that 
should be considered a style issue in the overall documentation.


Finally, in thinking some more about the fact that this is specifically 
intended to be used with Cray pointers: I think it's important to say 
explicitly in the MALLOC documentation that it is "intended to be used 
to allocate memory for use with Cray pointers (see 
$cray_pointer_documentation)", and that the ALLOCATE statement is used 
for allocating standard Fortran pointers.  Similarly, the FREE statement 
documentation should also reference DEALLOCATE.

I think we want to avoid a situation where someone new to Fortran could 
read through the documentation, get to MALLOC, and think, "Ah, this is 
how I should do dynamic allocation in Fortran!" without realizing that 
there's also a standard-conforming way to do it.  Personally, I'd almost 
prefer that the documentation say "Use ALLOCATE and proper Fortran-95 
pointers unless you've got a good reason not to," but I think that's 
really too opinionated to be appropriate.  :)

- Brooks