[m-dev.] for review: type specialization [1]

[Fergus Henderson]

On 18-Feb-1999, Simon Taylor <stayl at cs.mu.OZ.AU> wrote:
> This relative diff (full diff for reference_manual.texi) addresses
> your concerns, mostly changing the format of type subsitututions.
...
> Index: reference_manual.texi
> ===================================================================
> RCS file: /home/staff/zs/imp/mercury/doc/reference_manual.texi,v
> retrieving revision 1.120
> diff -u -r1.120 reference_manual.texi
> --- reference_manual.texi	1999/02/08 22:42:51	1.120
> +++ reference_manual.texi	1999/02/18 05:06:14
> @@ -3201,6 +3201,8 @@
>  * Impurity::                    Users can write impure Mercury code
>  * Inlining::                    Pragmas can be used to suggest or prevent
>                                  procedure inlining.
> +* Type specialization::		Produce specialized versions of polymorphic
> +				predicates.

s/predicate/procedures/

For consistency with the other menu entries, that should probably start
with "Pragmas can be used to produce ...".

>  * Obsolescence::                Library developers can declare old versions
>                                  of predicates or functions to be obsolete.
>  * Source file name::            The @samp{source_file} pragma and
> @@ -4422,6 +4424,83 @@
>  simply for performance concerns (inlining can cause unwanted code bloat
>  in some cases) or to prevent possibly dangerous inlining when using
>  low-level C code.
> +
> + at node Type specialization
> + at section Type specialization
> +
> +The overhead of polymorphism can in some cases be significant, especially
> +where polymorphic predicates make heavy use of class method calls or the
> +built-in unification and comparison routines. To avoid this, the programmer
> +can suggest to the compiler that a specialized version of a procedure should
> +be created for a specific set of argument types.
> +
> +A declaration of the form
> +
> + at example
> +:- pragma type_spec(@var{Name}/@var{Arity}, @var{Subst}).
> +:- pragma type_spec(@var{Name}(@var{Modes}), @var{Subst}).
> + at end example
> +
> + at noindent
> +suggests to the compiler that a specialized version of the named predicate
> +or function should be created with the type substitution given by
> + at var{Subst} applied to the argument types. The second form of the declaration
> +only suggests specialization of the specified mode of the predicate.

s/predicate/predicate or function/

(What happens if the specification is ambiguous?)

> An implementation is free to ignore @samp{pragma type_spec} declarations.

I suggest adding "An implementation is also free perform type specialization
even in the absense of any @samp{pragma type_spec} declarations."

Hmmm, maybe s/An implementation is/Implementations are/

> + at menu
> +* When to use type specialization::
> +* Implementation specific details::
> + at end menu

In general in TexInfo it is bad style to have a menu at the end of
a long section.  I suggest you change move that to after the
introductory paragraph, and move all the stuff between the introductory
paragraph and here into a new subsection called say "Syntax and semantics
of type specialization pragmas":

	@menu
	* Syntax and semantics of type specialization pragmas::
	* When to use type specialization::
	* Implementation specific details::
	@end menu

> + at node Implementation specific details
> + at subsection Implementation specific details
> +
> +The Melbourne Mercury compiler performs user-requested type specializations
> +when invoked with @samp{--user-guided-type-specialization}, which is enabled
> +at @samp{-O2}.

s/Melbourne/University of Melbourne/
s/@samp{-O2}/optimization level @samp{-O2} or higher/

> +The replacement types must be ground. A substitution such as
> + at w{@samp{T = list(U)}} is invalid. The compiler will warn about
> +such substitutions, and will ignore the request for specialization.
> +This restriction may be lifted in the future.

I suggest adding "In the current implementation, " before
"the replacement types must be ground.",
and changing the second sentence to "Substitutions such as
@w{@samp{T = list(U)}} are not supported."

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "Binaries may die
WWW: <http://www.cs.mu.oz.au/~fjh>  |   but source code lives forever"
PGP: finger fjh at 128.250.37.3        |     -- leaked Microsoft memo.