define-inlinable

[Ludovic Courtès]

Hello!

Andreas Rottmann <address@hidden> writes:

> From: Andreas Rottmann <address@hidden>
> Subject: Move `define-inlinable' into the default namespace
>
> * module/ice-9/boot-9.scm (define-inlineable): Moved here from SRFI-9.
> * module/srfi/srfi-9 (define-inlinable): Removed here.
>
> * doc/ref/api-procedures.texi (Inlinable Procedures): Add subsection
>   about `define-inlinable'.

Looks great to me.

Some nitpicking:

[...]

> address@hidden Inlinable Procedures
> address@hidden Inlinable Procedures
> +
> +You can define an ``inlinable procedure'' by using

Use @dfn{inlinable procedure} here.

> address@hidden instead of @code{define}. An inlinable procedure

I prefer two-spaces-after-period, but there’s no consensus.

> +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.

> 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!}.

> 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}).

> 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.
> +
> address@hidden {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.

Thanks,
Ludo’.