ludo@gnu.org (Ludovic Courtès) writes:

> Hello!
>
> Andreas Rottmann <a.rottmann@gmx.at> writes:
>
>> Subject: Move `define-inlinable' into the default namespace
>>
>> +@node Inlinable Procedures
>> +@subsection Inlinable Procedures
>> +
>> +You can define an ``inlinable procedure'' by using
>
> Use @dfn{inlinable procedure} here.
>
Done.

>> +@code{define-inlinable} instead of @code{define}. An inlinable procedure
>
> I prefer two-spaces-after-period, but there’s no consensus.
>
I try to use two spaces in English text as well, but being a German
native speaker (where this is against typographical rules, AFAIK), I
slip sometimes.  Fixed.

>> +behaves the same as a regular procedure, but direct calls will result in
>> +the procedure body being inlined into the caller.
>> +
>> +Making a procedure inlinable eliminates the overhead of the call,
>
> How about:
>
>   Procedures defined with @code{define-inlinable} are @emph{always}
>   inlined, at all call sites.  This eliminates function call overhead at
>   the expense of an increase in code size.
>
Folded in, with the addition of using ".., at _direct_ call sites.".
There's no inlining happening when you use `apply', or rebind the
procedure with `let'.  Should this be made more explicit?

>> but at
>> +the same time means that the caller will not transparently use the new
>> +definition if the inline procedure is redefined.
>
>   ... redefined using @code{set!}.
>
I don't agree with that one: there are multiple ways a procedure can get
"redefined", `set!' being just one of them.  I was actually thinking
more of re-evaluating the procedure definition or something like
`geiser-compile-file', hence I left the text like it was, being more
vague.

>> Inlinable procedures
>> +will also not deal nicely with debugging and tracing.
>
> Instead of “not deal nicely”, what about something like:
>
>   It is not possible to trace an inlined procedures or install a
>   breakpoint in it (@pxref{Traps}).
>
Done.

>> Therefore, you
>> +should not make a procedure inlinable unless it demonstrably improves
>> +performance in a crucial way.
>> +
>> +In general, only small procedures should be considered for inlining, as
>> +making large procedures inlinable will probably result in an increase in
>> +code size.  Additionally, the elimination of the call overhead rarely
>> +matters for for large procedures.
>> +
>> +@deffn {Scheme Syntax} define-inlinable (name parameter ...) . body
>
> I’d write “body ...” instead of “. body”.  Besides being aesthetically
> nicer, the former matches a proper list whereas the latter matches a
> pair.
>
Agreed, and done.

Updated patch attached, is it OK to push this way?